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INTRODUCTION 



This manual provides descriptive and operational information 
for the B 20 Indexed Sequential Access Method (ISAM) data 
management facility used by the B 20 family of workstations. 
ISAM provides efficient and flexible random access to data 
identified by multiple Keys. System designers and applica- 
tions programmers should use this manual to write ISAM 
applications used under BTOS. 

This manual consists of seven sections, four appendixes and 
an index: 

Section 1 Provides you with an overview of ISAM, 

including its features and installation 
instructions . 

Section 2 Introduces basic ISAM concepts which are 

explained in more detail in later 
sections. 



Section 3 Describes ISAM data sets and key types. 

Section 4 Describes the ISAM commands: ISAM COPY, 

ISAM CREATE, ISAM DELETE, ISAM RENAME, 
ISAM SET PROTECTION, ISAM STATUS, and 
ISAM TERMINATE. 

Section 5 Documents the ISAM REORGANIZE command. 

Section 6 Explains how to install and configure 

the ISAM server. 

Section 7 Describes ISAM operations by functional 

categories and presents all the 
operations in detail. 



Appendix A Contains the status codes and messages 

you could receive while using ISAM. 

Appendix B Describes the compatibility of earlier 

applications with this version of ISAM. 

Appendix C Explains how to estimate index file 

sizes . 

Appendix D Contains the glossary. 
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XI 



EXAMPLES IN THIS MANUAL 

This manual uses personnel data sets for examples and 
illustrations because they are familiar and provide 
continuity as the manual presents the various ISAM 
functional levels. 

Three data sets contain personnel information: an employ 
data set, a department data set, and a dependent data se 
The parameters included in each data set are: 

Employee data set, with one record per employee 

• department number 

• employee number 

• employee name 

• salary 

Department data set, with one record per department 

• department number 

• department name 

• employee number of department manager 
Dependent data set, with one record per dependent 

• employee number 

o number of dependents 

• dependent name 

• dependent date of birth 

REFERENCE MATERIAL 



The following manuals are referenced for additional 
information: 

B 20 Systems Operating System (BTOS) Reference Manual 

B 20 Systems Programmer's Guide, Part 1 

B 20 Systems Linker/Librarian Reference Manual 

B 20 Systems Sort/Merge Reference Manual 



xii 



SECTION 1 
OVERVIEW 



The B 20 Indexed Sequential Access Method (ISAM) is a 
software product that provides efficient, flexible random 
access to fixed-length records. These fixed-length records 
are identified by keys contained in the records. 

You can use 8086 Assembly, BASIC, COBOL, FORTRAN, and Pascal 
to write applications accessing ISAM. You can use ISAM on 
standalone, cluster, and master workstations . 

This section contains: 

• an overview of ISAM features 

• software installation procedures 

• memory and disk requirements 

• files necessary to run ISAM. 



FEATURES 



New ISAM 



features include: 



the ability of applications running on a cluster 
workstation to simultaneously access data sets 
located on the local and master workstations 



application or Executive access to remote ISAM 
data sets across a network (using B-NET) 



the ability to run one or more ISAM applications 
on each workstation (using the B 20 Context 
Manager) 



resident or swapping ISAM reorganization 



a utility to remove the ISAM server from a 
secondary partition of a multipartition system 



Standard 



ISAM features include: 



random access to data identified by multiple keys 
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• up to 100 keys in each ISAM data set 

• key types to support numerous character and 
numeric data representations 

• shared or exclusive access to ISAM data sets, 
with transactions and record-level or data set- 
level locking 

• resident or swapping ISAM server 

• ISAM data sets created from any fixed-length 
record Sequential Access Method file using 
ISAMReorganize 

• commands to perform maintenance and modifications 
to data sets and to provide status reports for 
data sets 



MEMORY AND DISK REQUIREMENTS 



ISAM requires 57KB of memory for the swapping version of the 
server and 90KB for the resident version. The minimum 
installation of ISAM software on hard disk requires 776 disk 
sectors. The full installation, including optional 
utilities, requires 1561 disk sectors. 

The following files constitute the minimum configuration of 
ISAM: 

ISAM.Config 
ISAMConf igure . Run 
ISAMCreate.Run 
ISAMDelete.Run 
ISAMRename . Run 
ISAMSetPro.Run 
ISAMServer .Run 

The following files comprise the optional ISAM utilities: 

ISAMCopy .Run 
ISAMReorganize . Run 
ISAMStatus . Run 
ISAMTerminate . Run 
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RELATED SOFTWARE 



ISAM requires Release 5.0 of BTOS . For networking applica- 
tions, ISAM requires B-NET, Release 1.0. Section 6 
discusses configuration requirements. 

INSTALLATION INSTRUCTIONS 



You install the ISAM software from the distribution 
diskettes . 



Hard Disk Systems 

To install ISAM on a hard disk system, use the following 
procedure : 

1. Sign on to a B 20 workstation and set your path to 
the system directory. 

2. Insert the first ISAM distribution diskette in 
floppy drive [f0]. 

3 . Type SOFTWARE INSTALLATION at the Executive 
prompt; then press GO. 

4. Follow all instructions shown on the display, and 
insert each of the other ISAM distribution 
diskettes when prompted. 

5. When installation is complete, remove the last 
diskette and store all of them in a safe place. 



Dual Floppy Standalone Systems 



To use ISAM on a dual floppy standalone system, prepare 
working copies (write-enabled) of the BTOS and ISAM 
diskettes. (For further information on making working 
copies, refer to the B 20 Systems Standard Software 
Operations Guide .) Then proceed as follows: 

1. Boot your system using a working copy of the BTOS 
boot diskette. 

2. Set your path to the system directory. 
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3. Insert a working copy of the second BTOS diskette 
in floppy drive [fO]. 

4. Insert the first ISAM diskette in floppy drive 
[fl]. 

5. Type SUBMIT at the Executive prompt, and press 
RETURN. 

6. Specify Cfl]<Create>ISAMFloppy.Sub in the SUBMIT 
form File list parameter. 

7. Press GO. 

8. Follow the instructions shown on the display. 

9. When installation is complete/ remove the 
distribution diskette and write-protect the ISAM 
diskettes . 



XE520 Systems 

To install ISAM on an XE520 system, use the following 
procedure: 

1. Sign on to a B 20 workstation clustered to an 
XE520 master, using the Administrator user name. 

2. Insert the first ISAM distribution diskette in 
floppy drive [fO]. 

3. Type SUBMIT at the Executive prompt and press 
RETURN. 

4. Specify [fO]<Sys>XEInstall.Sub in the SUBMIT form 
File list parameter. 

5. Press GO. 

6. Follow the instructions shown on the display. 

7. When the installation is complete, remove the last 
diskette and store all of them in a safe place. 
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The following information applies to the installation of 
ISAM on an XE520 system. 

• You should add the following statement to the 
INITFPOO.JCL file: 

$Run [Sys] <Sys>ISAMServer .Run, <number of users>, 
<conf iguration file> 

This statement must follow any entry for the queue 
manager and precede any entry for Mf AdminAgent . 

• Only one copy of the ISAM server can run on an 
XE520 system. You can install it on a board other 
than the master FP by inserting the statement 
$Run[Sys] <Sys>ISAMServer .Run, <number of users>, 
<conf iguration file> into the appropriate JCL 
file. It must precede any entry for a spooler. 

• You should make the statement NoWatchDog the first 
line in the Master. Cnf file. 

• The memory required (in kilobytes) is 64 + 4 
(number of users-4). 
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SECTION 2 
CONCEPTS 



ISAM allows you to access fixed-length data records 
contained in ISAM data sets. Each ISAM data set holds one 
type of data record. When you create an ISAM data set, you 
specify the record length and key fields, then access the 
records of a data set through fixed-length keys. You can 
define multiple key fields to support different access 
patterns . 



FILES TYPES 



ISAM stores each ISAM data set as two physical files: a data 
store file and an index file. You can place these two files 
on different physical volumes, provided they are on the same 
workstation . 

The data store file holds data records. Disk space 
management is efficient because all the records in a data 
set have the same length. Whenever you delete a record, the 
system marks it deleted, and adds it to a list of free 
records. The system can reuse these deleted records later 
to create a new record. The data store file is a Direct 
Access Method (DAM) file. 

The name of a data set is the same as the name of its data 
store file. You must supply a file specification for the 
data store file to access or create a data set. 

The index file holds indexes for all the keys of a data set. 
ISAM implements indexes by using a B-tree structure. The 
B-tree structure has several advantages: 

• support of both direct (by key) and sequential 
access 

• efficiency: 

- always takes the same number of I/O 
operations to reach a record 

never has to follow long overflow chains 
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uses two or three reads to locate a record 
and one to actually read the record 

• fast sequential access: maximum of three reads to 
locate and read the first record — usually a single 
read for each subsequent record 

• self-reorganization: automatic expansion to 
accommodate new keys 

• automatic compression: removal of keys to improve 
disk utilization and access efficiency 

ISAM separates data and indexes to allow the use of Record 
Sequential Access Method (RSAM) and DAM for read-only access 
to ISAM data set files. (For more information on RSAM, 
refer to the B 20 Systems Operating System (BTOS) Reference 
Manual. ) 

\ 

ISAM maintains logical dependencies between the data store 
file and index file of a data set; no access method other 
than ISAM can open or modify either file and a consistency 
check detects any invalid access. 

The separate data store and index files enable you to use 
the MAINTAIN FILE command to recover data from the data 
store file after hardware or software failure. 



Key Types 

A record can have up to 100 keys. The key position in the 
record describes the key. For example, the key position can 
show: 

• offset from the first byte of the record 

• key length 

• key type 

The ISAM key types support character and numeric represen- 
tations used by the B 20 programming languages and 
processors. Byte string and character string key types 
support character data. Numeric key types support integer, 
binary, packed decimal, display, and several forms of real 
numbers . 
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To increase flexibility, you can specify the following 
parameters for each key when you create an ISAM data set: 

• duplicate keys 

• index order (ascending or descending) 

• index size reduction (suppress null value key 
indexing ) 

Each key uses one index for retrieving a record. You can 
retrieve records in key-order sequence by any key field and 
starting with any key value. The system automatically 
updates the index when you store or modify records. 



UNIQUE RECORD IDENTIFIER 



A 4-byte unsigned integer uniquely identifies each record in 
a data set and is called the unique record identifier (URI). 
Store and Read operations return the record URI . Modify 
and Delete operations use URIs to identify the target 
records processed. 

URIs are valid only while the data set is open. You cannot 
save them to identify records once you close and reopen the 
data set. 



ISAM OPERATIONS 



ISAM supports four main operations on records: 
© storing 

• reading 

• modifying 

• deleting 



Storing Records 



When an application stores a new record, ISAM places the 
record in the data set. It then automatically indexes the 
record according to the values in all the key fields. 
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Reading Records 



When an application reads a record, ISAM retrieves any of 
the following: 

• a single record with a given unique key or unique 
record identifier 

• records with keys of a specific value (an exact 
match) 

• records with key values residing in a specified 
range (a range match) 

• records in which the beginning of a byte or 
character string key matches a particular value (a 
prefix match) 

The retrieval result can be either the specified records or 
a sequence of 4-byte unique record identifiers. If ISAM 
retrieves unique record identifiers, the application can 
obtain the corresponding records later by using a special 
form of the Read operation that does not reaccess the index. 



Modifying Records 

When an application modifies an existing record, ISAM 
automatically removes the record from each index for a 
changed key field. ISAM then indexes it under the new key. 



Deleting Records 

When an application deletes an existing record, ISAM removes 
the record from the data set. and from each individual index. 



DISTRIBUTED ISAM 

You can share ISAM files with users working at other 
workstations . 

For example, within a cluster system all cluster work- 
stations can access ISAM files located at the master. In 
addition, they can maintain local files at the cluster 
workstations if they have local file storage. You can 
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access ISAM files at the master and cluster workstations 
simultaneously. In this case, an application system could 
read a record from a data store file at the master and write 
a record to a data store file at the cluster. You must 
install the ISAM server at both workstations. 

In addition, you can use B-NET to access ISAM files located 
on other network workstations. You must specify the node 
name as part of the complete file specification. 

ISAM does not provide transactional monitoring. 



DATA SET ACCESS MODES 

You can use one of three modes to open a data set in ISAM: 

• administrator 

• batch 

• transaction 

Table 2-1 describes data set access modes. 

The use of read or modify affects the extent to which 
applications share a data set. 

You can share a data set opened in batch read mode if other 
users open it for read-only purposes. If you open a data 
set in batch read mode, the system denies any subsequent 
request to open the data set in administrator, batch modify, 
or transaction modify mode. 



Table 2-1. 
Mode 

Administrator 

Batch 

Transaction 



Description of Data Set Access Modes 
Activity 

data set-level activities (deleting ISAM 
files, renaming ISAM files, and setting 
protection on the file) 

open a data set in applications requiring 
exclusive use of the data set (use with 
read or modify) 

allows other applications to concur- 
rently access and modify the data set 
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You open a data set in batch modify mode exclusively; no 
other user has access to it. A request to open the data set 
in batch modify mode cannot execute if another user opened 
it in any mode. 

Using batch read, transaction read, or transaction modify 
modes, other users can open a data set you opened in 
transaction read mode. A request to open the data set in 
transaction read mode cannot execute if another user has the 
data set open in administrator or batch modify mode. 

Other users in either transaction read or transaction modify 
modes can open a data set you opened in transaction modify 
mode. You cannot execute a request to open the data set in 
transaction modify mode if another user has the data set 
open in administrator, batch read, or batch modify mode. 

A data set you open in administrator mode is open 
exclusively. A request to open the data set in 
administrator mode cannot be executed if another user has 
already opened it in any mode. 

Table 2-2 summarizes these rules. 



TRANSACTIONS 

An application can open a data set in batch mode to read or 
modify records. In batch mode, an application has exclusive 
access to the data set. Since other applications do not 
have access to the data set at the same time, you cannot 
make simultaneous updates. Modification of records and 
data sets does not affect any other application. 

If you open a data set in transaction mode for shared 
access, many applications can access the same records and 
data sets. Any modification of a record or data set by one 
application affects the other applications. Errors can 
occur if you do not coordinate simultaneous access. In 
ISAM, transactions are the coordination mechanism. 
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Table 2-2. Multiuser Access to Data Set Access Modes 



Initial Mode 



Valid Modes for New Open 



Administrator 



None 



Batch read 



Batch read 
Transaction read 



Batch modify 



None 



Transaction read 



Batch read 
Transaction read 
Transaction modify 



Transaction modify 



Transaction read 
Transaction modify 



In transaction mode, applications designed to allow 
multiuser access to a data sot divide their processing into 
a series of transactions. Each transaction is a unit of 
work, as shown in figure 2-1.- You must make changes to a 
data set within a transaction. Only after a completed 
transaction can other applications access the changed data. 

The beginning of a transaction is the BeginTransaction 
operation; the end of a transaction is either a 
CommitTransaction or a RollBackTransaction operation. 

You can perform some operations whether or not the applica- 
tion is in a transaction, but you must perform any operation 
that locks or modifies a record (or locks a data set) while 
the application system is in a transaction. Table 2-3 
illustrates this relationship. 



Locking a Record or Data Set 

During a transaction, an application can make certain 
changes to a data set. When an application system is in the 
midst of modifying data, the data set is not in a consistent 
state; ISAM prevents other applications from accessing the 
changed data. 
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Open Data Set 





Enter New Employee Data 
I 

Read User Input 

1 






Store New Records 




Report New Employee Number 



he 

Give a Raise 
I 

Read User Input 

Read Record 
Modify Record 



Determine Department Employees 
I 

Read Department Number 
I 

Read Records as Necessary 
I 

Print Names 
(No Modifications, No Transactions) 



TT 



Close Data Set 



Activities 



Transaction 



Figure 2-1. Series of Transactions 
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Table 2-3. Operations and Transactions 



Operations Allowed 

Only During a Transaction 

CommitTransaction 

DeletelSAMRecord 

DeletelSAMRecordByKey 

GetlSAMRecordsHold 

HoldlSAMDataSet 

HoldlSAMRecord 

Modi f y I SAMRecord 

ModifylSAMRecordByKey 

ReadlSAMRecordByUriHold 

ReadNextlSAMRecordHold 

ReadUniquelSAMRecordHold 

ReleaselSAMDataSet 

ReleaselSAMRecord 

StorelSAMRecord 



Operations Allowed At 
Any Time 

Close ISAM 

GetlSAMRecords 

ISAMRequest 

Norma lizelSAMStatus 

OpenlSAM 

QueryTr ansae tionParams 
ReadlSAMRecordByUri 
ReadNextlSAMRecord 
ReadUniquel SAMRecord 
RollBackTransaction 
SetTransactionParams 
SetUpISAMIterationLimits 
SetUpISAMIterationPref ix 



To prevent concurrent modification by multiple applications, 
ISAM allows an application to lock a record or data set. 
This ability gives the application exclusive access to the 
record or data set. 

Table 2-3 illustrates ISAM operations allowed during 
transactions. There are no transaction-related constraints 
for the following operations: CreatelSAM, DeletelSAM, 
LoadSingleUserlSAM, RenamelSAM, SetlSAMProtection, and 
VerifyMultiuserlSAM. ISAM does not allow BeginTransaction 
during a transaction. 

If an application locks a record, only that application has 
access to the record until ISAM releases or unlocks it. If 
an application locks a data set, only that application has 
access to the data set and all of its records until it is 
unlocked . 

Locking a record allows other application systems to access 
the remaining records of the data set. You should lock a 
data set only when necessary; locking prevents other 
applications from accessing any of the data set's records. 
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Deadlocks 



When more than one application attempts to lock the same 

record or data set, the first application to request the 

record or data set obtains it; other application requests 

queue up until the record or data set unlocks. 

A deadlock can occur when an application that locked a 
record or data set attempts to lock another record or data 
set that is locked by a different application. If the 
second application awaits the record or data set locked by 
the first application, both applications wait for the locked 
record or data set and can remain this way indefinitely. 
This deadlock becomes complicated when a number of applica- 
tions and requests are involved, as shown in figure 2-2. 

To avoid a deadlock, ISAM uses timeouts when an application 
requests a locked record or data set. You specify the 
maximum time a request can queue in the timeout value of the 
Transaction Parameters Block (refer to section 7). The 
timeout value, wTicksWait, specifies the maximum time a 
request waits to lock a record or data set. If the time 
specified in wTicksWait runs out, ISAM reports that the 
record or data set is not available. 



ISAM INSTALLATION 



You can use ISAM on a standalone workstation or in cluster 
configurations; it supports both single and multiuser 
access. An application loads single-user ISAM as a task, 
and you install multiuser ISAM as a system service. You can 
install multiuser ISAM in either a single-partition or 
multipartition operating system. 

In a single-partition operating system, you install ISAM 
permanently in memory. Once you install ISAM, you cannot 
remove the ISAM server, nor can you reallocate its memory 
without bootstr aping BTOS. 

In a multipartition BTOS, you install ISAM in a secondary 
application partition. (For further information about 
secondary application partitions, refer to the B 20 Systems 
Operating System (BTOS) Reference Manual . ) 
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Lock 





Figure 2-2. 



Complex Deadlock 
Deadlock ( Samples ) 



ISAM Configuration File 



An ISAM configuration file specifies the sizes of the ISAM 
server's memory areas, based on the number of users. ISAM 
provides default values for this file. Additionally, there 
is a utility that modifies the file to improve ISAM's 
performance or reduce memory requirements. 

ISAM COMMANDS 

ISAM provides commands that you can use from the Executive 
to maintain and modify ISAM data sets: 

© ISAM COPY 

• ISAM CREATE 

• ISAM DELETE 

• ISAM RENAME 

e ISAM REORGANIZE 

0 ISAM SET PROTECTION 

e ISAM STATUS 

• ISAM TERMINATE 

Table 4-1 describes these commands. 

DATA SECURITY 



Two associated passwords provide data security at each ISAM 
data set level: read and modify. In addition, BTOS protects 
the files of an ISAM data set from unauthorized access. 



DATA INTEGRITY 



ISAM includes features for maintaining and monitoring the 
integrity of data on disk files through: 

© Error logging 

The system logs errors discovered in the ISAM file 
structures in the file [Sys ] <Sys>Log . Sys . You can 
use the PLOG command to display the log contents. 

• Internal consistency checking 

Hardware or software errors can introduce 
anomalies into a data set. ISAM algorithms 
minimize these anomalies by detecting them where 
possible and preventing them from becoming worse. 

© Write-through cache 

ISAM maintains and uses a set of I/O buffers that 
bring segments of disk records into memory as 
needed. Whenever ISAM stores or modifies a 
record, ISAM writes the changed data in the 
buffers back to disk. ISAM always updates the 
disk before completing an operation that changes a 
data set. 

This policy makes the data less susceptible to 
damage from hardware or software failures, unless 
the failure occurs in the middle of a Modify, 
Store, or Delete operation. ISAM updates all 
files; no partial modifications remain in memory 
without updating the disk. 

If hardware or software failures damage an ISAM data set, 
you can recover undamaged records by using the MAINTAIN FILE 
command, then you can use the ISAM REORGANIZE command to 
reconstruct the data set. 
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SECTION 3 
ISAM DATA SETS 



This section discusses the concept and specifics of ISAM 
data sets. An ISAM data set consists of two physical files: 

• a data store file that contains fixed-length 
records 

• an index file containing keys and addresses of the 
records in the data store file 

There is a logical dependency between the data store file 
and the index file of a data set. 



INDEXES AND KEYS 



An index is a structure designed to help you locate a 
particular record of a data set. ISAM bases index keys on 
the key field values for records contained in a data set. 
Index keys can be in ascending or descending order. 
Figure 3-1 illustrates an index for a data set. 

An application uses an index to: 

• read records in key order 

• read a single record using a unique key 

An example of sequential access using personnel data sets is 
reading the employee records in order by employee number, 
from 100 to 999. An example of direct access is reading the 
employee record for employee number 15. 

Both of these examples read the records using an employee 
number index. To access records directly, the index must 
contain unique keys. Unique keys indicate that only one 
record exists for each key value. In this case, you cannot 
use duplicate keys. 

Index keys can be simple or composite. A single field 
comprises a simple key. ISAM sorts an index composed of 
simple keys in the natural order for the key type. This 
allows applications to sequentially access records in order 
by key value. Multiple fields make up a composite key. 



5022247 



3-1 



empNo Index 



Employee Data Set 





Emp. No. 


Dept. No. 


Emp. Name 


Salary 


1561 


1000 


Smyth 


$40,000 


1785 


5000 


Smith 


$30,000 


1242 


5000 


Jones 


$40,000 


1794 


5000 


Kelly 


$29,000 


1413 


1000 


Adams 


$30,000 






• 








• 








• 








• 








• 





Figure 3-1. Data Sot Index (Sample) 



ISAM uses the first field to sort an index composed of 
composite keys. The second field in a series sorts groups 
of records with duplicate values for the first field, and so 
forth. If the entire key contains duplicates, ISAM accesses 
records with duplicate values in random order. If a 
composite key is unique, no duplication is possible. 

In composite keys: 

• total key length cannot exceed 64 bytes 

• all fields must be character or byte strings 

• sort order must be ascending or descending for all 
fields 

• fields must be adjacent in the records and appear 
in order of significance 
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For example, for a data set with the following structure: 



Byte 



Length 



Type 



Name 



0 
4 



4 
5 



Byte string 
Byte string 



deptNo 
empNo 



You can define a composite key (deptNo, empNo) , but not 
( empNo, deptNo) . The order of the fields does not permit 
( empNo, deptNo) keys. 

A single key field can also define a composite key. Using 
the example above, you define the composite key 
(deptNo, empNo) as a 9-byte byte string key located at 
offset 0. 



Key Types 



ISAM supports different type3 of keys by which you can use 
most data representations specified in each of the B 20 
programming languages. You can use 12 different key types 
to specify an index. Each of the 12 types has a notation 
for non-COBOL applications (types 0 to 11) and a corres- 
ponding notation for COBOL applications (types 20 to 31). 

Table 3-1 describes each key type. For more information on 
the relationships between key types and programming language 
representations, refer to table 3-2. 



Table 3-1. Description of Key Types 



Key 



Description 



Binary 



an unsigned 1-byte to 8-byte integer 



The high-address byte of a binary key is 
significant for determining sort order 
on the workstation processor. For 
COBOL COMP fields, the low-address byte 
is most significant. 
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Table 3-1. Description of Key Types (Cont) 



Key 

Byte String 



Character String 



Decimal (Odd)/ 
Decimal (Even) 



Display 



Description 

an uninterpreted fixed-length string of 
1 to 64 binary bytes 

The low-address byte is most significant 
for determining sort order; ISAM distin- 
guishes between uppercase and lowercase 
ASCII characters. Byte strings have the 
same representation in all programming 
languages, including COBOL. 

a fixed-length string of 1 to 64 binary 
bytes 

ISAM sorts a character string with the 
low-address byte as most significant for 
determining sort order. ISAM sorts 
character string keys with no distinc- 
tion between uppercase and lowercase 
ASCII characters; character strings have 
the same representation in all program- 
ming languages, including COBOL. 



contains two decimal digits in each 
byte, except for the last (high-address) 
byte where the rightmost four bits are 
sign-reserved 

This format is the same as COBOL COMP-3 . 
You use decimal (odd) for values that 
have odd numbers of digits and decimal 
(even) for values with even numbers of 
dxgits. The number of digits before 
packing determines if the system uses 
the odd or even decimal type. A decimal 
key can contain 1 to 18 decimal digits. 

for USAGE is DISPLAY numeric fields 

It supports all of the COBOL sign 
options. Display keys can be 1 to 19 
bytes long, containing 1 to 18 decimal 
digits . 
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Table 3-1. 



Description of Key Types (Cont) 



Key 



Description 



Integer 



a signed 1-byte to 8-byte integer 



Long /Short /Extended 



IEEE 



The high-address byte of an integer key 
is the most significant for determining 
sort order in a workstation applica- 
tion. For COBOL COMP fields, however, 
the low-address byte is the most 
significant . 



for real numbers in Pascal or FORTRAN 
applications 



Long/Short Real 



A long IEEE key is 8 bytes long; a short 
IEEE i3 4 bytes; an extended IEEE is 10 
bytes . 

for BASIC applications 



A long real key is an 8-byte real 
number; a short real key is a 4-byte 
real number. 



Table 3-2. ISAM Key Types and Programming Language 
Representations 

Language and Key Type cblndexField wType 

BASIC Interpreter 

Integer (%) 2 7 

ShortReal ( 1 ) 4 5 

LongReal (#) 8 4 
BASIC Compiler 

Integer (%) 2 7 

ShortReal (!) 4 5 

LongReal (#) 8 4 
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Table 3-2. ISAM Key Types and Programming Language 
Representations (Cont) 



Language and Key Type 
COBOL 

USAGE is DISPLAY (n-byte) 
(numeric types) 

USAGE is COMP (n-byte) 
(signed) 

USAGE is COMP (n-byte) 
(unsigned) 

USAGE is COMP-3 (n-digit) 
(n even) 

USAGE is COMP-3 (n-digit) 
FORTRAN (Microsoft) 
INTEGER* 2 
INTEGER*4 
REAL* 4 
REAL*8 

DOUBLE PRECISION 
FORTRAN-86 

(same as FORTRAN above) 

TEMPREAL 
Pascal (Microsoft) 

Byte 

Integer 

Real 

SInt 

Word 



cblndexField 



(n+2)/2 
(n+2)/2 

2 
4 
4 
8 
8 



10 

1 
2 
4 
1 
2 



wType 

31 
27 
20 
26 
23 

7 
7 
9 
8 
8 



10 

0 
7 
9 
7 
0 
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SECTION 4 
ISAM UTILITIES 



This section describes the Executive ISAM commands you can 
use for data set maintenance. Each command requires 
exclusive control of the data set. Table 4-1 describes each 
command . 

Section 5 describes ISAM REORGANIZE; you use ISAM REORGANIZE 

to recover lost data and to build a data set from any 
standard access method file with fixed-length records. 

Section 6 describes ISAM INSTALL; you use ISAM INSTALL to 

install the multiuser ISAM server. 



Table 4-1. ISAM Commands 



Command 
ISAM COPY 

ISAM CREATE 

ISAM DELETE 

ISAM RENAME 

ISAM SET PROTECTION 
ISAM STATUS 



Description 

copies data set files to produce a 
new data set (The passwords for the 
new data set remain the same.) 

creates an empty data set with the 
specified record size and index 
fields 

deletes both the data store and index 
files of the data set and destroys 
all the data 

renames the data store and index 
files to rename the data set (The 
passwords are unchanged. ) 

changes the passwords used to gain 
access to an existing data set 

displays information about a data set 
(ISAM can also print information or 
write it to a disk file.) 



5022247 



4-1 



Table 4-1. ISAM Commands (Cont) 



Command 



Description 



ISAM TERMINATE 



removes the ISAM server from a 
secondary partition in a 
multipartition system 



DEFAULT INDEX FILE NAME 



Several ISAM commands include an optional field for an index 
file specification. If you do not enter a file specifica- 
tion, the data store file specification issues one by 
default. ISAM copies the file specification for the data 
store and replaces the suffix with .Ind. 

For example, if the file specification for the data store is 
[vol] <dir>DataSet . Isam, the file specification for the index 
file is [vol]<dir>DataSet. Ind. If the data store file is 
DataSet, the index file is DataSet.Ind. 



The ISAM COPY command creates a new data set by copying an 
existing one. The command copies both the data store file 
and the index file of the existing data set. Figure 4-1 
illustrates the ISAM COPY form. Table 4-2 describes the 
ISAM COPY form parameters. 



ISAM COPY 

ISflfl data set fron {:,,,, '. '. 7a 

ISAM data set to 
[Index file to] 
[Overwrite ok?] 



ISAM COPY 



Figure 4-1 . 



ISAM COPY Form 
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Table 4-2. ISAM COPY Form Parameters 



Parameter 

ISAM data set from 

ISAM data set to 
[Index file to] 



[Overwrite ok?] 



Description 

file specification for the data 
store file ISAM copies (If you 
supply a password, it must be the 
volume, directory, or file password 
for both data set files.) 

file specification for the new data 
set's data store file (The pass- 
word must be the volume or direc- 
tory password for the new data 
store file . ) 

file specification for the index 
file of the new data set 

ISAM derives the default file 
specification from the data store 
file specification, described in 
this section. The password must be 
the volume or directory password 
for the new index file. 

If you specify Yes, ISAM performs 
the copy. If existing files have 
the same names, ISAM overwrites 
them without issuing a confirmation 
message . 

The default (No) directs ISAM to 
display a prompt to confirm over- 
writing the file (if it exists). 
Overwriting a file destroys the 
data. You press GO to confirm the 
overwrite, or press CANCEL or 
FINISH to deny it. 
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The following example copies a new data set from an existing 
one. 



ISAM COPY 
ISflfl data set from 
ISAM data set to 
[Index file to] 
[Overwrite ok?] 



Enployee.lSffl 
EnployeeNeu.ISAI 



Since you did not enter the index file specification, ISAM 
creates the default index specification, EmployeeNew.Ind. 
If a file called EmployeeNew. ISAM or EmployeeNew.Ind already 
exists, ISAM prompts for an overwrite confirmation by 
default. 



ISAM CREATE 



The ISAM CREATE command creates an empty data set with the 
record size and index fields that you enter on the ISAM 
CREATE form. Figure 4-2 illustrates the ISAM CREATE form. 

Table 4-3 describes the fields of the ISAM CREATE form. 



ISM Create 

ISAM data set [ 
[Index file] 

Record size (e.g., 20 bytes) 
Index keys (e.g.. Byte: 10.8. ANU.U) 
[B-tree node size (default 2 sectors)] 
[Growth increnent for data store file (default 30 sectors)] 
[Growth increnent for index file (default 30 sectors)] 
[Initial size of data store file (default 30 sectors)] 
[Initial size of index file (default 30 sectors)] 
[Overwrite ok?] 



Figure 4-2. ISAM CREATE Form 



Table 4-3. ISAM CREATE Form Parameters 



Parameter 

ISAM data set 



[Index file] 



Record size 

(e.g. , 20 bytes) 



Index keys (e.g. , 
Byte: 10.8. ANU.W) ] 



Description 

file specification ISAM creates for 
the data set's data store file (The 
password must be the volume or 
directory password for the new data 
store f ile . ) 

file specification for the new data 
set's index file 

The default is described in this 
section. The password you supply 
must be the volume or directory 
password for the new Index file. 



byte size of the records in the new 
data set. 

Records must be at least 4 bytes 
long. Maximum record size is 
65,528 bytes. 



parameter list specifying the index 
fields of the data set 

You specify each parameter in the 
list using the following format; do 
not embed spaces. 

t:l.o.anu.w or t.o.anu.w 

t is the field type and can be any 
of the following: 

Binary 
Byte 

Character 

Decimal 

Display 

Integer 

LonglEEE 

ShortlEEE 

ExtendedlEEE 

LongReal 

ShortReal 



5022247 



4-5 



Table 4-3. ISAM CREATE Form Parameters (Cont) 



Parameter 



[B-Tree node size 

(default 2 sectors)] 



[Growth increment for 
data store file 
(default 30 sectors)] 
[Growth increment for 
index file (default 
30 sectors)] 
[Initial size of data 
store file (default 
30 sectors)] 



Description 

1 is the field length in bytes 

for byte or character strings, 
number of digits for decimal, 
or number of bytes for binary, 
display, and integer numbers 

Binary fields default to two 
bytes if you omit this entry. 
Long, short, and extended IEEE 
index fields and long and 
short real index fields do not 
use this entry. 

o is the byte offset in the 
record for the index field 
(You specify it as a decimal 
number. ) 

a represents ascending key 

order; D represents descending 
Key order 

n indexes null values (binary 

O's); S suppresses null values 

u represents a unique key; D 
permits duplicate keys 

w is for non-COBOL applications; 
M is for COBOL applications 
(This field is optional; 
default is W. ) 



number of sectors in the B-tree 
nodes for new data set (maximum 
value is 12 sectors) 



Table 4-3. ISAM CREATE Form Parameters (Cont) 



Parameter Description 

[Initial size of index 
file (default 30 

sectors)] values used to avoid wasting disk 

space and disk fragmentation 
caused by excessive numbers of disk 
extents 



[Overwrite ok?] If you specify Yes, the system 

creates the data set. 

The default (No) directs the system 
to display a prompt to confirm 
overwriting the existing file when 
either of the files for the new 
data set exists. Overwriting an 
existing file destroys the data in 
it. You can press GO to confirm 
the overwrite, or press CANCEL or 
FINISH to deny the overwrite. 



The following example creates the Employee data set from the 
Personnel example. 



ISW1 Create 

ISAM data set Enployee.ISffl 

[Index file] 

Record size (e.g., 20 bytes) 43 
Index keys (e.g., Byte:10.8.ANU.U) 

[B-tree node size (default 2 sectors)] aEnployee.Keys 

[Growth increnent for data store file (default 30 sectors)] 

[Growth increnent for index file (default 30 sectors)] 

[Initial size of data store file (default 30 sectors)] 

[Initial size of index file (default 30 sectors)] 

[Overwrite ok?] 
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The data set name is Employee . ISAM, and the index file is 
Employee . Ind, by default. The record size is 43 bytes. 
Employee .Keys is a text file containing the following index 
definitions : 

BYTE:5.4.ANU.W 
CHARACTER : 3 0 . 9 . AND . W 
BYTE:9.0.ANU.W 

The data store, index file sizes, and growth increments use 
default values. You create both files with an initial size 
of 30 sectors. Each time either of the files is full, the 
length extends by 30 sectors. 

By default, you receive a prompt to confirm overwriting if 
either Employee . ISAM or Employee. Ind exists. 



ISAM DELETE 

The ISAM DELETE command deletes both the data store file and 
the index file of the data set. It destroys all the data in 
the data set. 

There is only one parameter in the ISAM DELETE form: ISAM 
data set. This is the file specification for the data store 
file. The password you supply must be the volume, 
directory, or file password for both files of the data set. 

The following example deletes the Employee data set of the 
Personnel example. The system deletes all records in 
Employee . ISAM and all indexes in Employee . Ind . 



ISAM Delete 

ISflfl data set Enployee.ISffl 



ISAM RENAME 



The ISAM RENAME command changes the name of an existing data 
set by renaming both the data store file and the index file. 
You must rename both files. 
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The system implements ISAM RENAME by using two invocations 
of the BTOS RenameFile operation: one changes the data store 
file name; the other changes the data set index file name. 

There are certain RenameFile operations that are invalid 
(renaming a file from one volume to another, or renaming a 
file using an incorrect password). If one of the two 
required BTOS RenameFile operations is invalid, ISAM RENAME 
detects the error. It then renames the data set using a 
valid name for both the data store and index files. In this 
case, one or both of the files can retain the original name. 

Figure 4-3 illustrates the ISAM RENAME form. 

Table 4-4 describes the parameters of the ISAM RENAME form. 



ISfltt Renane 

ISfltt data set fron .............. \ 

ISAM data set to 
[Index file to] 
[Overwrite ok?] 



Figure 4-3. ISAM RENAME Form 



The following example renames the Employee data set of the 
Personnel example 

ISAM Renane 

ISAM data set fron Enployee.ISAtl 
ISAM data set to <Neu0ir>Enployee.ISft1 
[Index file to] 
Overwrite ok?] 

The renamed data store file is the same, but it now resides 
on a different directory on the logged-in volume. The data 
set file specification constructs the index file specifica- 
tion by default. The new index file name is 
<NewDir > Employee . Ind. 
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Table 4-4. ISAM RENAME Form Parameters 



Parameter 

ISAM data set from 



ISAM data set to 



[Index file to] 



[Overwrite ok?] 



Description 

file specification of the renamed 
data set's data store file (The 
password must be the volume, 
directory, or file password for 
both files of the data set.) 

file specification for the renamed 
set's data store file (The volume 
must be the same volume specified 
in ISAM data set from. The 
password must be the volume or 
directory password for the renamed 
data store file.) 

file specification for the renamed 
data set's index file (If you do 
not make an entry, ISAM derives the 
default index file specification as 
described in this section.) 

The volume must be the same volume 
on which the existing index file 
resides. The password must be the 
volume or directory password for 
the new index file. 

Specify Yes to rename a data set 

The default (No) directs the system 
to display a prompt to confirm 
overwriting the existing file (if 
either of the files for the new 
data set already exists). Over- 
writing an existing file destroys 
the data in it. You can press GO 
to confirm the overwrite, or press 
CANCEL or FINISH to deny it. 



ISAM SET PROTECTION 

The ISAM SET PROTECTION command enters or modifies passwords 
that permit access to a data set. ISAM SET PROTECTION does 
not change file system passwords for the files of the data 
set. You can change file system passwords using the 
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Executive SET PROTECTION command. Passwords also open data 
sets in administrator mode (refer to section 2 for more 
information on the use of administrator mode). 

Figure 4-4 illustrates the ISAM SET PROTECTION form. 

Table 4-5 explains the parameters on the ISAM SET PROTECTION 
form. 



ISAM Set Protection 

ISAM data set E : : : : : x:xft*fo 
[Password for nodification] 
[Password for reading] 



Figure 4-4. ISAM SET PROTECTION Form 



Table 4-5. ISAM SET PROTECTION Form Parameters 



Parameter 



Description 



ISAM data set 



file specification for the data 
store file of the data set (This is 
the data set whose passwords you 
are modifying. The password must 
be the volume, directory, or file 
password for both files of the data 
set . ) 



[Password for 
modification] 



[Password for reading] 



new password for modify access to 
the data set (Without this 
password, any password permits 
modify access; passwords have a 
maximum length of 12 characters.) 

new password for read access to the 
data set (Without this password, any 
password permits read access; pass- 
words have a maximum length of 12 
characters . ) 
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The following example protects the Employee . ISAM data set 
for read and modify access. 

ISAM Set Protection 

ISAI1 data sat Enployoe.IStfl 

[Password for nodification] xxy 

[Password for reading] xxz 

Command password requirements are as follows: 

• batch and transaction read modes require either 
xxy or xxz 

• batch and transaction modify modes require xxy 

• administrator mode requires the file system 
password 

ISAM STATUS 

The ISAM STATUS command produces a status report for a data 
set on the display; you can also print or write it to a disK 
file. The information displayed includes: 

file names 

sizes 

growth increments 
record and B-tree node sizes 

description of each index, including the depth of 
each B-tree 

If you enter Yes in response to [Details?], the command 
includes the following additional information: 

• number of records (and deleted records) in the 
data set 

• number of B-tree nodes for each index (and the 
number of deleted nodes) 

• number of records indexed under each key 

e average percentage of node space currently used 
for each index's node 
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Retrieving this additional information involves scanning the 
files of the data set; ISAM STATUS takes significantly 
longer to execute if you request these details. 

Figure 4-5 illustrates the ISAM Status form. 

Table 4-6 explains the parameters of- the ISAM STATUS form. 



ISAH Status 
ism data set 
[Log file] 
[Details?] 



Figure 4-5. ISAM STATUS Form 



Table 4-6. ISAM STATUS Form Parameters 

Parameters Description 

ISAM data set file specification for the data 

store file for which you want the 
status report (The password you 
use must be the volume, directory, 
or file password for both files of 
the data set.) 

[Log file] file specification for the file the 

system writes the status report to 
(If you do not specify a log file, 
the report appears only on the 
display. ) 

[Details?] Specify Yes to display additional 

details . 

The default (No) directs the system 
to display the standard informa- 
tion. (Refer to ISAM STATUS 
information, in this section.) 

The following example produces a status report with details 
shown in the second part of figure 4-6. Figure 4-6 shows 
both forms of the ISAM STATUS report. 
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ISAM Status 
ism data set Enployee.ISfft 
[Log file] 
[Details?] Yes 

/ 



ISAM TERMINATE 

The ISAM TERMINATE command removes the ISAM system service 
from memory. You can use this command only on a multi- 
partition operating system and only at the workstation at 
which you installed ISAM. ISAM TERMINATE has no parameters. 



Data store file 

Index file 

Last accessed 

Last modified 

Record size (bytes) 

Node size (sectors) 

Size of Data store file (sectors) 

Size of Index file (sectors) 

Growth increment for Data store file (r.ectorn) 
Growth increment for Index file (sectors) 
Number of records (valid and deleted) 
Number of nodes (valid and deleted) 



|Win] <Personnel>Empl oyee . ISAM 

(Win) < Per sonne 1 > Employee . Ind 

Thu Jul 11 , 1985 1(1: 09 AM 

Thu Jul 11, 1985 1(1:09 AM 

43 

2 

5 

10 

5 

5 

7 

3 



Index Index 
Number Specification 
0 Byte:5.4.ANU.W 

Character : 30. 9 .AND. w 
Byte:9.0.ANU.W 



tlTrec 
Depth 
1 
1 
1 




Data store file 

Index file 

Last accessed 

Last modified 

Record size (bytes) 

Node size (sectors) 

Size of Data store file (sectors) 

Size of Index file (sectors) 

Growth increment for Data store file (sectors) 

Growth increment for Index file (sectors) 

Number of records 

Number of deleted records 

Number of nodes 

Number of deleted nodes 



[Win) <Porsonnel> Employee. ISAM 
[Win) <Pcr sonnel>Employee . Ind 
Thu Jul 11, 1985 10:09 AM 
1985 10:09 AM 



Thu Jul 
43 

2 
5 

10 
5 
5 
7 



11. 



Index Index BTree 

Number Specification Depth 

0 Byte:5.4.ANU.W 1 

1 Character:30.9.AND.W 1 

2 Byte:9.0.ANU.W 1 



Number 
of nodes 



Number of 
records indexed 
7 
7 
7 



Average 
Fullness (%) 



Figure 4-6. ISAM STATUS Reports (Samples) 
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SECTION 5 
ISAM REORGANIZATION 



The ISAM REORGANIZE command builds a data set from any 
Standard Access Method file of fixed-length records, 
including the data store file of a data set. 

You can use this command independently to: 

• initially load a data set from a Direct Access 
Method (DAM) file 

• change the definition of the indexes of an 
existing data set or add new indexes 

• change CreatelSAM parameters, such as B-tree node 
sizes 

You can use this command with the MAINTAIN FILE command to: 

• recover records from a data set damaged by a 
software or hardware failure 

• reclaim space in a data set from which you deleted 
records 

• merge several data sets or DAM files into a new 
data set 

You can use this command with the SORT command (described in 
the B 20 Systems Sort/Merge Reference Manual ) to: 

• sort the physical records to organize the data set 
in order by key values 

• recover records, reclaim space, and merge data 
sets (as with the MAINTAIN FILE command) 

• modify records by changing, adding, deleting, or 
rearranging parameters 

Sorting the records of a data set improves the performance 
of applications that access the records of the data set in 
the sort order. No other difference is visible at the 
application level. 
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The ISAM distribution diskette contains two forms of the 
ISAM REORGANIZE run file: resident and swapping. Hard disk 
systems automatically install the swapping version on the 
disk, but dual floppy systems systems use only the resident 
version. The resident version uses more memory than the 
swapping form, but performance is better. 

ISAM REORGANIZE performs an in-place reorganization. The 
DAM file or the data store file of the data set becomes the 
data store file of the reorganized data set. ISAM deletes 
the index file of the data set and then rebuilds it. 

At the end of this section, there are examples of how to use 
ISAM REORGANIZE alone or with MAINTAIN FILE or SORT to 
perform the tasks described previously. Figure 5-1 
illustrates the ISAM REORGANIZE form. 

Table 5-1 explains the parameters on the ISAM REORGANIZE 
form. 



ISflfl Reorganize 




ISflfl data set or Off! file |: 


[Index file] 




[Work file 1] 




[work file 2] 




[Use paraneters fron ISAM data set?] 




[Index keys (e.g., Byte:10.8.ANU.U)j 




[B-tree node size (2 sectors)] 




[Data store file growth increnent (30 sectors)] 




[Index file growth increnent (30 sectors)] 




[Initial index file size (30 sectors)] 




[flaxinun initial B-tree node fullness (80%)] 




[Overwrite ok?] 





Figure 5-1. ISAM REORGANIZE Form 



Table 5-1. ISAM REORGANIZE Form Parameters 



Parameter 

ISAM data set 
or DAM file 



[Index file] 



Description 

file specification for a data set 

If you specify a DAM file, the DAM 
file becomes the data store file of 
the new data set. ISAM REORGANIZE 
can determine whether the file is a 
DAM file or an ISAM data set by the 
content of the data file or ISAM 
data set. 

file specification for the index 
file of the reorganized data set 

If the file specified in the ISAM 
data set or DAM file is an existing 
data set, the index file name 
defaults to the name of the exist- 
ing index file for the data set. 
If Index file changes an existing 
data set index file name, ISAM 
deletes the old index file. 



If the ISAM data set or DAM file 
above specifies the name of a DAM 
file, the index file name defaults 
to the name of the DAM file with 
the suffix . Ind. 

[Work file 1] two work files, each approximately 

[Work file 2] cRecords* ( sKeyMax + 8) + 512 bytes 

long 

(The number of records in the data 
set is cRecords, and sKeyMax is the 
length of the longest key parameter 
in bytes . ) 

The work files default to 
[Sys] <$nnn>ISAMWorkltmp and 
[Sys]<$nnn>ISAMWork2tmp (nnn is the 
workstation number). 
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Table 5-1. ISAM REORGANIZE Form Parameters (Cont) 



Parameter Description 

If the directory [Sys]<$nnn> does 
not exist, the work files default 
to ISAMWorKltmp and ISAMWork2tmp in 
the logged-in directory (using the 
logged-in default file prefix) . 

You can optimize ISAM REORGANIZE 

performance by putting the work 
files on different Winchester disk 
drives . 

[Use parameters from 

ISAM data set?] If you specify Yes, ISAM reorgan- 

izes an existing data set. If you 
leave any of the parameters in the 
form blank from [Index keys (e.g., 
Byte:10.8.ANU.W)] through [Index 
file growth increment (30 
sectors) ] f ISAM uses the values you 
specified when you created or last 
reorganized the data set, instead 
of the listed defaults. 

If you specify Yes for this 
parameter and the index file of the 
data set was deleted or unusable, a 
status message appears on the 
display and ISAM REORGANIZE 
terminates . 

If you accept the default (No), for 
this parameter, you must fill in 
Clndex keys (e.g., 

Byte:10.8.ANU.W)]. If you do not 
fill in any of the parameters 
[B-tree node size (2 sectors)], 
[Data store file growth increment 
(30 sectors)], or [Index file 
growth increment (30 sectors)], 
ISAM uses the listed default. 



5-4 



Table 5-1. ISAM REORGANIZE Form Parameters (Cont) 

Parameter Description 

Index keys (e.g. , 

Byte: 10.8. ANU.W) ] parameter list that specifies the 

index parameters of the data set 

You specify each parameter in the 
list using the following format, 
with no embedded spaces. 

t:l.o.anu.w or t.o.anu.w 

t is the field type and can be 
any of the following: 

Binary 
Byte 

Character 

Decimal 

Display 

Integer 

LonglEEE 

ShortlEEE 

ExtendedlEEE 

LongReal 

ShortReal 

1 is the length of the field in 
bytes for byte or character 
strings, the number of digits 
for decimal, or the number of 
bytes for binary, display, and 
integer numbers 

If you omit this entry, binary 
parameters default to two 
bytes. Long, short, and 
extended IEEE index parameters 
and long and short real index 
parameters do not use this 
entry. 

o is the byte offset in the 
record for the index 
parameter. You specify it as 
a decimal. 



5022247 



5-5 



Table 5-1. ISAM REORGANIZE Form Parameters (Cont) 



Parameter 



[B-tree node size 
(2 sectors)] 



[Data store file 

growth increment 

(30 sectors)] 
[Index file growth 

increment (30 

sectors ) ] 
[Minimum index file 

size (30 sectors)] 



[Maximum initial 
B-tree node full- 
ness (80%)] 



, Description 

a represents ascending key 

order; D represents descending 
key order 

n indexes null values (binary 

O's); S suppresses null values 

u represents a unique key; D 
permits duplicate keys 

w is for non-COBOL applications; 
M is for COBOL applications 
(This parameter is optional; 
default is W. ) 



number of sectors in B-tree nodes 
for new data set (Maximum value is 
12 sectors . ) 



values you use to avoid wasting 
disk space and disk fragmentation 
(caused by excessive numbers of 
disk extents) 



percentage of allocated space for 
maximum capacity of each B-tree 
node; minimum capacity 50% 

(If you specify a percentage less 
than 50%, ISAM REORGANIZE ignores 
it and uses 50% . ) 
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Table 5-1. ISAM REORGANIZE Form Parameters (Cont) 

Parameter Description 

[Overwrite ok?] If you specify yes, the system 

performs the reorganization without 
confirmation prompts. 

Under any of the following con- 
ditions, ISAM REORGANIZE issues a 
prompt to confirm before 
overwriting the file contents: 

• you accept the default (No) 

• the ISAM data set or DAM file 
entry specifies a DAM file 

• the index file exists 



LOADING A DATA SET 



By using the Executive COPY command, you can load a data set 
from a DAM file. You copy the DAM file to the data store 
file of the data set. Then you Use ISAM REORGANIZE to build 
the indexes for the new data set and to initialize all file 
structures necessary for ISAM's access to the data set. 

If the DAM file, Employee. DAM, contains records to load into 
the Employee data set, Employee . ISAM, you copy Employee. DAM 
to Employee . ISAM. The following example illustrates this 
operation . 

Copy 

File fron Employee. Dtfl 

File to Enployee.ISAfl 

[Overwrite ok?] 
[Ccnfirn each?] 
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After invoking ISAM REORGANIZE, you fill in the form as 
follows: 



ISflH Reorganize 

ISAfl data set or Dtfl file Enployee.ISfft 
[Index file] 
[Work file l] 
[work file 2] 

[Use parameters fron ISAM data set?] 

[Index keys (e.g., Byte:l0.8.ANU.W)] aEnployee.Keys 

[B-tree node size (2 sectors)] 

[Oata store file growth increnent (30 sectors)] 

[Index file growth increnent (30 sectors)] 

[Initial index file size (30 sectors)] 

[flaxinun initial B-tree node fullness (801)] 

[Overwrite ok?] 



Employee .Keys is a text file containing the following key 
specifications: 

BYTE:5.4.ANU.W 
CHARACTER : 3 0 . 9 . AND . W 
BYTE:9.0.ANU.W 



CHANGING INDEXES AND OTHER ISAM CREATE PARAMETERS 

You can use ISAM REORGANIZE to: 

• change the index definitions of an existing data 
set 

• add new indexes 

• change other ISAM CREATE parameters such as B-tree 
node sizes 
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In the Personnel data sets example, the records 
Employee . ISAM have the following structure: 



contained in 



Offset 



Length 



Parameter 



Type 



0 
4 
9 
39 



4 
5 
30 
4 



deptNo 
empNo ' 
empName 
salary 



byte 
byte 

character 
decimal 



EmpNo and empName are defined as keys; there is also a 
composite key (deptNo, empNo) . 

In this example, you added an index on the salary parameter. 
All four indexes now list records in ascending order by key 
parameter(s) , and all four now support indexing of null 
values. The empName and salary indexes allow duplicates; 
and the empNo and (deptNo, empNo) keys uniquely identify 
records. 

When the ISAM REORGANIZE form appears, you enter the name of 
the data set in the ISAM data set or DAM file parameter. 
Then you specify Yes for [Use parameters from ISAM data 
set?], and fill in the parameters you want changed. 



ISAM Reorganize 
ISAM data set or DAM file 
[Index file] 
[Uork file 1] 
[Uork file 2] 

[Use paraneters fron ISAM data set?] 
[Index keys (e.g.;. Byte:10.8.ANU.U)] 
[B-tree node size (2 sectors)] 
[Data store file growth increnent (30 sectors)] 
[Index file grouth increnent (30 sectors)] 
[Initial index file size (30 sectors)] 
[Maxinun initial B-tree node fullness (80%)] 
[Overwrite ok?] 



Enployee.ISffl 



Yes 

aEnployee.Keys 
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Employee. Keys is a text file containing the following key 
specifications: 

BYTE:5.4.ANU.W 
CHARACTER : 3 0 . 9 . AND . W 
BYTE:9.0.ANU.W 
DECIMAL: 6. AND. W 

ISAM REORGANIZE then: 

• extracts the old parameters from the data set 

• replaces any that have new values with specified 
values (in this case, only the index keys) 

• rebuilds the indexes of the data set 

RECOVERING RECORDS, RECLAIMING SPACE, 
AND MERGING DATA 

You use the Executive MAINTAIN FILE command and ISAM 
REORGANIZE to: 

• recover records from a data set damaged by a 
software or hardware failure 

• reclaim space in a data set from which you deleted 
records 

• merge several data sets or DAM files into a new 
data set 

MAINTAIN FILE performs each of these tasks and produces a 
single file. This file, along with ISAM REORGANIZE, builds 
the indexes. 

The following example shows you how to recover data from 
Employee. I SAM. You first invoke MAINTAIN FILE and fill in 
the form as follows: 

naintain File 
Input files Enployee.ISOl 
[Output file] Tenp.Dfln 
[Log file] 

[Renove deleted records?] 
[Suppress confirnation? 
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MAINTAIN FILE scans the data store file of the Employee data 
set, verifying the file structures, recovering data, and 
reclaiming the space the deleted records occupied. Then 
ISAM copies the records copied into Temp. DAM. 

Next, you use the Executive COPY or RENAME command to 
replace the data store file of Employee . ISAM with the file 
that MAINTAIN FILE produces, as follows: 

Renane 

Old file nane Teflp.Drtl 
New file nane Enployee.ISrtl 

[Overwrite ok?] Yes 
[Confirn each?] 

Finally, you use ISAM REORGANIZE to build the indexes of the 
merged data set. The existing index file can supply the 
index Keys, node sizes, etc. (If the index file of the old 
Employee . ISAM data set does not have the default name, 
Employee . Ind, you must specify its name in the Index file 
parameter. ) 



ISAM Reorganize 

ISAM data set or DAM file Enployee.ISOl 
[Index file] 
[work file 1] 
[work file 2] 

[Use paraneters fron ISAtt data set?] 

[Index keys (e.g., Byte:10.8MU.W)] Yes 

[B-tree node size (2 sectors)] 

[Data store file growth increnent (30 sectors)] 

[Index file growth increnent (30 sectors)] 

[Initial index file size (30 sectors)] 

[flaxinun initial B-tree node fullness (80%)] 

[Overwrite ok?] 



SORTING DATA SET RECORDS 

You use the SORT command and ISAM REORGANIZE to: 

• sort the physical records to organize the data set 
in order by key values 
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• recover records, reclaim space, and merge data 
sets 

• modify records by changing, adding, deleting, or 
rearranging parameters 

You modify records by using the Own Code feature in the SORT 
utility. After ISAM sorts the data store file ISAM 
REORGANIZE builds the indexes for the data set. (For more 
information on Sort, refer to the B 20 Systems Sort/Merge 
Reference Manual . ) 

In the Personnel data sets example, the Employee data set, 
Employee. ISAM, has the following parameters. 



Offset Length Parameter Type 

0 4 deptNo byte 

4 5 empNo byte 

9 30 empName character 

39 4 salary decimal 



EmpNo and empName are key parameters and ( deptNo, empNo ) is a 
composite key. 

In this example, a major application system processes 
records in order by employee number, so it is advantageous 
to sort the data set by the empNo parameter. You should 
invoke SORT and fill in the form as follows: 

Sort 

Input files Enployee.ISffll 
Output files Tenp.Wtl 
Keys BYTE:5.4.A.U. 

[Stable sort?] 
[Work file 1 
[Uork file 2] 
[Log file] 

[Suppress confirnation] 

Next, you use the Executive COPY or RENAME command to 
replace the data store file of Employee . ISAM with the file 
SORT produces, as follows: 



Renane 

Old file nane Tenp.DOl 
New file nane Enployee.ISrtl 
[Overwrite ok?] Yes 
[Confirn each?] 
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Finally, you use ISAM REORGANIZE to build the sorted data 
set's indexes. The existing index file can supply the index 
keys, node sizes, etc. (If the index file of the old 
Employee . ISAM data set does not have the default name, 
Employee . Ind, you must specify its name in the Index file 
parameter . ) 



ISAfl Reorganize 

ism data set or Dm file Enployee.ISOl 
[Index file] 
[Uork file 1] 
[Uork file 2] 

[Use paraneters fron ISflfi data set?] 

[Index keys (e.g.. Byte:10.8ANU.W)] Yes 

[B-tree node size (2 sectors)] 

[Data store file growth increnent (30 sectors)] 

[Index file growth increnent (30 sectors)] 

[Initial index file size (30 sectors)] 

[Maxinun initial B-troo node fullness (80%)] 

[Overwrite ok?] 



5022247 



5-13 



SECTION 6 
ISAM SERVER INSTALLATION 



ISAM supports both multiuser and single-user access to the 
ISAM server. The system installs multiuser ISAM in memory 
as a system service, while an application loads single-user 
ISAM as a task. If the system installs multiuser ISAM, 
applications can share access to data sets. An application 
that opens a data set with single-user ISAM, however, has 
exclusive use of the data set; no other application can 
access that data set. 

ISAM handles the differences between multiuser and single- 
user access internally. Once ISAM establishes access, 
applications are independent of any differences and can run 
in either environment. (Refer to table 6-1 for more infor- 
mation on the differences between multiuser and single-user 
access . ) 

For example, ISAM treats transaction-related constraints 
associated with multiuser access the same way that it does 
single-user access. Using the same requirements regardless 
of access method enables you to write and test an applica- 
tion in a single-user environment before using it in a 
multiuser environment. 

Similarly, asynchronous requests from applications to ISAM 
use the same procedure, ISAMRequest, in both multiuser and 
single-user environments. 

To support multiuser (shared) access to data sets, you must 
install the ISAM server in memory as a system service at a 
standalone, master, or cluster workstation. You use the 
ISAM INSTALL command to install multiuser ISAM. The ISAM 
distribution diskettes contain a default configuration file 
that you can modify to support the requirements of your 
installation. 

You can also load ISAM as a task of an application by 
invoking the LoadSingleUserlSAM operation. Loading the ISAM 
server from an application allows single-user exclusive 
access to data sets located at the workstation where the 
application is running, without installing ISAM as a system 
service. 
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You can install two different forms of the ISAM server: 
resident and swapping. The resident server uses more memory 
than the swapping form, but performance is better. 

The distribution diskettes include both forms; the type of 
system environment in which you are using ISAM determines 
which form you use. Hard disk systems automatically install 
the swapping server on the disk. Systems equipped with 
floppy disk drives use only the resident server. 



MULTIUSER INSTALLATION 

The following information pertains to multiuser installation 
in a single-partition BTOS and in a multipartition BTOS. 



Single Partition Operating System 



In a single-partition operating system, the system 
permanently installs ISAM in memory. Once you install it, 
you cannot remove it or reallocate its memory, unless you 
reset the system. 



Table 6-1. Differences Between Multiuser and 
Single-User Access 



Multiuser Access 

ISAM installs 

as a system service at 

the master, cluster, or 

stand-alone work 

station. 



Single-User Access 

ISAM loads as a 

task of the application. 



ISAM services requests 
from all applications. 



Both shared and 

exclusive access to 

a data set are available. 



ISAM services requests only 
from the application 
that called it. 

Only exclusive access 
to a data set available; 
no other application can 
access a data set that an 
application opened. 



ISAM uses Request and 
Respond operations and 
asynchronous processing. 



ISAM uses the Send 
operation for asynchronous 
processing. 



Multipartition Operating System 



In a multipartition operating system, the system installs 
ISAM in a secondary application partition. You can use the 
ISAM TERMINATE command to remove the server from a secondary 
partition. 



ISAM INSTALL 



The ISAM INSTALL command installs the ISAM server in memory 
at a standalone, cluster, or master workstation. It uses 
the values contained in a configuration file to determine 
how to allocate memory. Figure 6-1 illustrates the ISAM 
INSTALL form. 



Memory Allocation 



ISAM server installation requires memory for: 

• resident code and data 

• a virtual code segment management buffer (swap 
zone) when it uses the swapping server 

• a heap 

• data and index buffers 



ISAM Install _________ 

[Nunber of ISAM users (default fron OS configuration)] | : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :^ 
[Configuration file (default [Sys]($ys)ISAf1 -Config)] 



Figure 6-1. ISAM INSTALL Form 
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Table 6-2. ISAM INSTALL Form Parameters 



Parameter Description 

[Number of ISAM users 
(default from OS 

configuration)] specifies the average number of 

users who use ISAM 

(The default is the total number of 
users specified in the BTOS system 
build configuration file. ISAM 
determines memory requirements for 
the specified number of users 
according to the values specified 
in the configuration file for the 
data set . ) 



For example, if a cluster has five 
users, three of whom use ISAM 
extensively and two of whom use 
ISAM occasionally, you should 
specify four. ISAM allows simul- 
taneous use by all five with some 
performance degradation. 

[Configuration file 
(default [Sys]<Sys> 

ISAM.Conf ig) ] specifies the configuration file 

ISAM uses to determine memory 
requirements 

(The default value is 
[Sys] <Sys>ISAM. Conf ig, which is the 
configuration file you receive with 
the distribution diskettes. To 
modify the default configuration, 
refer to ISAM CONFIGURE, in this 
section. ) 



Resident Code and Data 



The following are the code and data requirements for the 
swapping and resident servers. You can specify other memory 
areas, although the distribution configuration file contains 
default values. 
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Resident code and data 
(swapping system service): 39K 

Resident code and data 
(resident system service): 80K 



Swap Zone 

For the resident ISAM server, the swap zone size is 
always 0. The size of the swap zone can vary for the 
swapping server. In general, the more memory allocated for 
the virtual code segment, the better ISAM performs. For the 
swapping form of the ISAM server, the size of the swap zone 
(virtual code segment management buffer) must be at least 8K 
of memory; the maximum amount is 48K of memory. 



Heap 

The heap is an area of memory containing internal ISAM data 
structures that allocates control blocks for open data sets, 
indexes, and record locks. If you need a large number of 
control blocks, you should increase the heap size; however, 
the size of the heap cannot exceed 40K of memory. This 
section provides further information on determining heap 
size . 



Data Buffers 



Data buffers are fixed-length I/O buffers into which ISAM 
reads portions of data files. ISAM allocates data buffers 
as 512-byte sectors. A data buffer must be at least two 
sectors (IK) and not more than 127 sectors (63. 5K). The 
buffer size should be kept small unless the records in the 
data set are large. 

You determine the total memory area allocated for the data 
buffers by multiplying the number of sectors needed for a 
buffer by the total number of buffers required. The number 
of users determines the number of buffers needed. 

This section provides information on how to determine the 
number of buffers needed; it also gives a more detailed 
explanation of how to determine the data buffer size. 
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Index Buffers 



Index buffers are fixed-length I/O buffers into which ISAM 
reads portions of index files. The system allocates Index 
buffers as 512-byte sectors. An index buffer must be at 
least one sector (512 bytes) and no more than 12 sectors 
(6K). You cannot access a data set if the largest B-tree 
node in the index file does not fit in the index buffer. 
The system allocates nodes, like index buffers, in full 
sectors. The index buffer must be no smaller than the 
largest B-tree node. You determine total memory area 
allocated for the index buffers by multiplying the number of 
sectors needed for a buffer by the number of buffers needed. 

The number of buffers required depends on the number of 
users. This section provides further information on 
determining the number of index buffers you may need. 



ISAM CONFIGURE 

An ISAM configuration file specifies the sizes of the ISAM 
server's memory areas; you determine size according to the 
number of users you specify. The configuration file 
provided on the distribution diskette has default values for 
these memory areas. However, changing the values with the 
ISAM CONFIGURE command can improve performance, depending on 
the typical patterns of access in a particular installation. 

The ISAM CONFIGURE command creates or changes the 
configuration file that the ISAM INSTALL command uses to 
determine memory allocation (refer to ISAM INSTALL, 
described in this section). ISAM CONFIGURE displays the 
values contained in the specified configuration file and 
allows you to change the values. 

If the specified configuration file does not exist, ISAM 
CONFIGURE creates a new configuration file with the 
specified name, and inserts default values. The following 
message appears before ISAM CONFIGURE creates the 
configuration file. (In this case, the term file refers to 
the specified configuration file.) 

File file does not exist. Create? 

(Press GO to confirm, CANCEL to stop command) 
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If the specified configuration file exists but is not an 
ISAM configuration file, ISAM CONFIGURE overwrites the 
contents of the configuration file with default 
configuration values. The following message appears before 
ISAM CONFIGURE overwrites the contents of the specified 
configuration file: 

File is not an ISAM configuration file. 
Overwrite? 

(Press GO to confirm, CANCEL to stop command) 

By changing the values in the form, you can modify tne 
configuration file values. This section also provides 
detailed information on calculating the size of the memory 
areas. Figure 6-2 illustrates the ISAM CONFIGURE form. 



ISAM Configure 

[Configuration file (default ($ys3<Sys>ISAf1.Config)] 



Figure 6-2. ISAM CONFIGURE Form 



The default configuration file is [Sys]<Sys>ISAM.Conf ig, 
which is the configuration file provided with the 
distribution diskettes. 



ISAM Configure Display 

The ISAM CONFIGURE display appears when you invoke the 

command. The values from the configuration file specified 

in ISAM CONFIGURE appear. (Refer to figure 6-3.) 

By changing the entries in the form, you can change the 
configuration file. 



Cursor Movement 



When the ISAM CONFIGURE display appears, the cursor is in 
the first field. If you press the NEXT, RETURN, or TAB key, 
the cursor moves from field to field. When the cursor 
reaches the last field, pressing the NEXT or RETURN key 
brings the cursor to the first field. 
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The cursor-control keys move the cursor vertically or 
horizontally as follows: 



• The Left Arrow and Right Arrow keys move the 
cursor within a field. 

• SHIFT-Lef t Arrow moves the cursor to the previous 
field. 

• SHIFT-Right Arrow moves the cursor to the next 
field (the same as the NEXT and RETURN keys). 

• The Up Arrow, SHI FT- Up Arrow, and SHI FT- Down Arrow 

keys move the cursor vertically. 

o CODE-Up Arrow moves the cursor to the first field. 

• CODE-Down Arrow moves it to the last field. 

To delete one or more characters, you use the following key 
or set of keys: 

• Press DELETE to delete one character at a time in 
a field. 

• Press CODE-DELETE to delete all field characters. 



Display 

The following items describe the ISAM CONFIGURE display. 
They correspond to the circled numbers in figure 6-3. 

(lj ISAM Configuration Utility X.XX is the display 
title. X.XX is the version. 

(2) Buffer Sizes (number of 512-byte sectors) 

specifies the number of 512-byte sectors to be 
allocated for each data and index buffer. The 
maximum number of sectors for data buffers is 127; 
the index buffer maximum is 12. The default value 
for both data and index buffers is 2. 

(T) Number of ISAM Users specifies the range of 
numbers ISAM uses as column headings for the 
tabular portion of the form. Each entry is the 
number of users for which that column provides 
configuration information. You can specify up to 
10 numbers. You can change the range of numbers 
as long as the numbers ascend from left to right. 
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Executive X.XX (OS XXX-X.XX) 
Path: [Sys]<Sys> 



User Nane: Allen 

Fri July 26. 1985 1:47 P.M. 



(?) ISffll Configuration Utility X.XX 

(T) Buffer Sizes (nunber of 512-byte sectors) 



0 
© 

© 
© 



Data Buffers 2_ 
Index Buffers 2 



Heap Size 

(K bytes) 
Data Buffers 

(nunber) 

Index Buffers 
(nunber) 



1 


2 


© 

3 


Nunber of ISM Users 
4 5 6 16 


32 


48 


64 


4 






13 


16 


28 


36 


50 


63 


3 






8 


10 


20 


36 


52 


66 


3 






16 


20 


40 


72 


104 


132 



Swap Zone Size (K bytes) 10 



Press GO to confirn changes, or CANCEL to stop connand 



© 



Figure 6-3. ISAM CONFIGURE Display (Sample) 



Heap Size (K bytes) specifies the number of bytes 
allocated for the heap, based on the number of 
users. The minimum size is 1. 



There must be at least one entry in this row. 

(T) Data Buffers (number) specifies the number of data 
buffers allocated, based on the number of users. 
The minimum number is 2. 

There must be at least one entry in this row. 

MS J Index Buffers (number) specifies the number of 
index buffers allocated, based on the number of 
users. The minimum number is 3. 

There must be at least one entry in this row. 
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Swap Zone Size (K bytes) specifies the number of 
bytes allocated for virtual code segment 
management. The minimum number is 8. The 
resident server ignores this entry. 

Message line. Error messages replace this line if 
any errors occur. 



MEMORY ALLOCATION CALCULATION 

Before installing the server, ISAM INSTALL allocates memory 
by calculating the memory requirements for resident code and 
data, a swap zone (if you use the swapping server), a heap, 
and data and index buffers. 

You predetermine memory allocation for resident code and 
data; the configuration file specifies memory allocation for 
the swap zone. 

ISAM INSTALL uses the configuration file values listed in 
the ISAM CONFIGURE display (see figure 6-3) to calculate 
memory allocation for the heap and the data and index 
buffers, based on the number of users accessing ISAM. 

ISAM INSTALL calculates the heap size by selecting the Heap 
Size entry for the appropriate number of users. If the 
specified number of users is a column entry, ISAM INSTALL 
then reads the specified heap size from that column in the 
Heap Size row. If ISAM INSTALL does not find that number of 
users, or if the corresponding column in the Heap Size row 
is blank, it calculates heap size by either interpolating 
between or extrapolating from the existing entries. 

ISAM INSTALL calculates the memory area needed for the data 
buffers from two entries in the configuration file. Then it 
determines the actual number of data buffers to use in the 
same way it determines heap size, using the Data Buffers 
(number) entries in the tabular section of the form. ISAM 
INSTALL then multiplies this number by the Buffer Sizes 
entry for data buffers. The product is the size of the 
memory area allocated for all the data buffers. This 
section provides further information on calculating the size 
of the data buffers. 

ISAM INSTALL calculates the memory area the index buffers 
need in the same way it calculates the area the data buffers 
need; it uses the Index Buffers entries. 




For example, the default configuration file contains the 
heap size and the number of data and index buffers for 1, 4, 
6, 16, 32, 48, and 64 users. If you specify four users 
during installation, then ISAM INSTALL allocates 13K-bytes 
of memory for the heap, eight 1024-byte data buffers, and 16 
1024-byte index buffers. 

If you specify three users in the previous example, ISAM 
INSTALL interpolates values for the heap size and the number 
of data and index buffers, then calculates their memory 
allocation. If you specify more than 64, ISAM INSTALL 
extrapolates the values for the heap size and the number of 
data and index buffers. ISAM INSTALL then calculates their 
memory allocation. 



BUFFER SIZE GUIDELINES 

Whenever ISAM reads a record or B-tree node into memory, it 
reads in the entire record or node. Therefore, buffers must 
be large enough to accommodate the largest record or B-tree 
node. Data buffers must be large enough to hold the largest 
record in the data set. This requirement becomes complex 
because records can overlap sector boundaries, but I/O 
operations always access whole sectors. If a record 
overlaps two sectors, ISAM must read both sectors into the 
data buffer. 

The rule for allocating data buffers is: 

buffer size (bytes) = record size (bytes) + overhead 
(8 bytes) + overlap sector (511 bytes), rounded up to 
full sectors 

If the record size + 8-byte overhead is a power of 2, the 
records align on sector boundaries, and the calculation does 
not need the extra 511 bytes for sector overlap. 

The number of buffers allocated depends on the number of 
users. The minimum is two data buffers. Random-access 
performance improves with more buffers because this 
increases the probability that a record still exists in 
memory if you need it a second time. Sequential-access 
performance improves with larger buffers. 
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SECTION 7 
ISAM OPERATIONS 



You use the ISAM procedures and services in applications to 
operate on data in ISAM data sets. You can write ISAM 
applications in any of the B 20 programming languages. 

Table 7-1 categorizes procedures and services by function. 
The first part of this section contains brief descriptions 
and general information on each functional category. The 
operations are then presented in alphabetical order with a 
brief description of the operation, the procedural inter- 
face, and the request block parameters where applicable. 

You access most ISAM services by a procedural interface or 
by the ISAMRequest and Wait operations. You use the 
ISAMRequest operation to send requests to ISAM; multiuser 
ISAM uses the Request operation while single-user ISAM uses 
the Send operation. 

Using the procedural interface is easier because the system 
performs most of the work automatically. Using the 
ISAMRequest and Wait operations allow for a greater degree 
of overlap between computation and I/O operations. 

Previous applications can use operations that are no longer 
standard in Release 5.0. Programs that call these 
operations still run with ISAM 5.0. Appendix B lists 
services that are no longer part of standard ISAM 
operations . 



STATUS BLOCK 

All ISAM operations include the pStatusBlockRet parameter, 
which points to the address of a status block used to report 
errors to the application. The 4-byte status block contains 
two status codes, ere and ercDetail, as shown in table 7-2. 

Ere is either 0 (OK) or one of the ISAM status codes listed 
in appendix A. If ere is nonzero, ercDetail gives addi- 
tional information about the error, for example, when a sec- 
tor of the index file becomes unreadable because of a device 
error. Ere contains 3119 (Index file error) and ercDetail 
contains 301 (I/O error). 
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Table 7-1. ISAM Operations by Function 



Data Set Management 



Record Locking 



CreatelSAM 
DeletelSAM 
RenamelSAM 
SetlSAMProtection 



HoldlSAMDataSet 
HoldlSAMRecord 
ReleaselSAMDataSet 
ReleaselSAMRecord 



Data Set Access 



Transactions 



CloselSAM 
OpenlSAM 



BeginTransaction 
CommitTransaction 
QueryTransactionParams 
RollBackTr ansae t ion 
SetTransactionParams 



Record Management 

DeletelSAMRecord 

DeletelSAMRecordByKey 

ModifylSAMRecord 

ModifylSAMRecordByKey 

StorelSAMRecord 



ISAM Service Access 

Loads ingleUser ISAM 
VerifyMultiuserlSAM 



Single Record Access 

ReadlSAMRecordByUri 
ReadlSAMRecordByUriHold 
ReadUniquelSAMRecord 
ReadUniquelSAMRecordHold 

Multiple Record 
Access (Iteration) 

GetlSAMRecords 

GetlSAMRecordsHold 

ReadNextlSAMRecord 

ReadNextlSAMRecordHold 

SetUpISAMIterationLimits 

SetUpISAMIterationPref ix 



Asynchronous Requests 

ISAMRequest 
NormalizelSAMStatus 



Table 7-2. Status Block Format (pStatusBlockRet Parameter) 



Offset 

0 



Size 
(bytes) 



Parameter 

ere 



Contents 

Status code 
(see appendix A) 



ercDetail 



Detail status code 
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If you use ISAM operations within a COBOL application, the 
two bytes of each status code appear in reverse order. You 
can display the status codes correctly by first calling 
ConvertWord for each status code. 



DATA SET MANAGEMENT 



Table 7-3 describes data set management operations 
Section 3 describes ISAM data sets. 



ISAM DESCRIPTION BLOCK 



When you create a data set with the CreatelSAM operation, an 
ISAM Description Block supplies a data set description that 
includes the record size, key description, and sector allo- 
cation policies. Table 7-4 illustrates the block structure. 



Table 7-3 

Operation 

CreatelSAM 

DeletelSAM 
RenamelSAM 

SetlSAMProtection 



Data Set Management Operations 

Description 

data set index structure; creates a 
new, empty data set with the 
specified structure 

deletes the open data set files, 
and destroys the data set 

changes the name of an existing 
data set (the data store and index 
file name) 

changes the data set passwords 
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Table 7-4. ISAM Description Block 



Offset 

0 



Parameter 

If alnitSize- 
IndexFile 



Size 
(bytes) 



qbGrowIndex- 
File 



cSectorsNode 



10 



If alnitSize- 
DataStoreFile 



Description 



initial index file size 
of the data set (It must 
be a multiple of 512. 
The size defaults to 
15360, 30 sectors, if 
If alnitSizelndexFile 
is 0. ) 



number of bytes by which 
the index file grows 
when memory is exhausted 
(The value must be a 
multiple of 512. The 
index file grows by a 
default of 15360, 30 
sectors, if 

gbGrowIndexFile is 0.) 

B-tree nodes size in 
sectors (cSectorsNode 
must not exceed the 
index buffer size speci- 
fied in the configura- 
tion file you use to 
install ISAM. It 
defaults to that buffer 
size . ) 



initial data store file 
size of the data set 
(It must be a multiple 
of 512. The size 
defaults to 15360, 30 
sectors, if 

If alnitSizeDataStoreFile 
is 0. ) 
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Table 7-4. ISAM Description Block (Cont) 



Offset 

14 



Size 

Parameter (bytes) 

gbGrowData- 
File 4 



18 



20 



sRecord 



clndexes 



Description 



number of bytes by which 
the data store file 
grows when file space is 
gone (The value must be 
a multiple of 512. The 
data store file grows by 
a default of 15360, 30 
sectors if 
gbGrowDataStoreFile 
is 0. ) 

size in bytes of data 
set records (Records 
must be at least four 
bytes . ) 

number of data set 
indexes 



22 



rglndexSpec Indexes 
*20 



data set Index Specifi- 
cation Blocks (There is 
one ISAM Index Specifi- 
cation Block per index. 
The ISAM Index Specifi- 
cation Block structure 
is shown in table 7-5.) 



Table 7-5. ISAM Index Specification Block 



Offset 

0 



Parameter 

rblndexField 

cblndexField 



Size 
(bytes) 



Description 

key component offset in 
each data set record 

key component size in 
bytes (The fields wType 
and cblndexField together 
specify the type and size 
of the key component in 
each ISAM Index specifi- 
cation Block. Refer to 
table 7-6. ) 
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Table 7-5. ISAM Index Specification Block (Cont) 



Size 

Offset Parameter (bytes) Description 

4 wType 2 one of the values 0 to 11 

(20 to 31 for COBOL) used 
to represent a key type 
as in table 7-6 (The 
fields wType and 
cblndexField together 
specify the type and size 
of the key component in 
each ISAM Index Specifi- 
cation Block. Refer to 
table 7-6. ) 



6 fAscending 2 



8 fNullIsIndexed 2 



10 fDuplicates- 

Allowed 2 



12 pad 8 



TRUE (OFFh) if keys for 
this index are in ascend 
ing order; FALSE (Oh) if 
the keys are in descend- 
ing order 

TRUE (OFFh) if null 
values (binary 0's) are 
indexed? FALSE (Oh) if 
null values are not 
indexed 



TRUE (OFFh) if duplicate 
values are valid for this 
index; FALSE (Oh) if ISAM 
prevents a record from 
being stored or modified 
when a key value dupli- 
cates the key of a data 
set record 

When f DuplicatesAllowed 
is FALSE, you use index 
to directly access the 
data set records; each 
key is unique 

Reserved 
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Table 7-6. Type of Key Component 



Type Name of Type 

0 Binary 

1 Byte 

2 Character 

3 Decimal (Odd) 

4 LongReal 

5 ShortReal 

6 Decimal (Even) 



7 Integer 

8 LonglEEE 

9 ShortlEEE 

10 ExtendedlEEE 

11 Display 



COBOL applications use 
listed in this table. 



Description 

cblndexField contains the key 
length in bytes (1 to 8 are 
valid values) 

cblndexField contains the key 
length in bytes (1 to 64 are 
valid values) 

cblndexField contains the key 
length in bytes (1 to 64 are 
valid values) 

cblndexField contains (d + 
2)/2; d is the number of 
decimal digits in the key 
(d < 18) 

cblndexField must contain 8 

cblndexField must contain 4 

See Decimal (Odd) above for 
the value of cblndexField 

(You use this type for keys 
with an even number of decimal 
digits . ) 

cblndexField contains the key 
length in bytes (1 to 8 are 
valid values) 

cblndexField must contain 8 

cblndexField must contain 4 

cblndexField must contain 10 

cblndexField contains the key 
length in bytes (1 to 19 are 
valid values . ) 

the values 20 to 31 for the key types 
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DATA SET ACCESS 



There are two Data Set Access and ISAM handle operations: 

CloselSAM (closes an open data set) 

OpenlSAM (opens an existing data set) 

An ISAM handle is a word value which identifies an open data 
set. The OpenlSAM operation returns the ISAM handle; in 
subsequent ISAM operations you use it as the parameter 
ISAMhandle. An ISAM handle is valid until you close or 
delete the data set. 



RECORD MANAGEMENT AND ACCESS 

Table 7-7 describes Record Management Operations, table 7-8 
describes Single Record Access Operations, and table 7-9 
describes Multiple Record Access (Iteration) Operations. 



Table 7-7. Record Management Operations 
Operation Description 



DeletelSAMRecord 



DeletelSAMRecordByKey 



ModifylSAMRecord 



ModifylSAMRecordByKey 



StorelSAMRecord 



removes a data set record 
(identified by its unique record 
identifier) 

removes a data set record 
(identified by a unique key) 

modifies an existing record 
(identified by its unique record 
identifier) in the data set and 
updates all indexes accordingly 

modifies a data set record (identi- 
fied by a unique key) and updates 
all indexes accordingly 

creates a new data set record with 
specified data 
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Table 7-8. Single Record Access Operations 



Operation 

ReadlSAMRecordByUri 



ReadlSAMRecordByUri- 
Hold 



ReadUniquelSAMRecord 

ReadUniquelSAMRecord- 
Hold 



Description 

reads a record identified by its 
unique record identifier 



reads and locks a record identified 
by its unique record identifier 

reads a record identified by a 
unique key 

reads and locks a record identified 
by a unique key 



Table 7-9. Multiple Record Access (Iteration) Operations 
Operation Description 



GetlSAMRecords 



GetlSAMRecordsHold 



ReadNextlSAMRecord 

ReadNextlSAMRecord- 
Hold 

SetUpISAMIter at ion- 
Limits 



SetUpISAMIter at ion- 
Prefix 



reads several records or unique 
record identifiers in key order 

reads and locks several records or 
unique record identifiers in key 
order 

reads the next record in key order 

reads and locks the next record in 
key order 



initializes a sequence of Read 
operations for records with a 
specific key within a given range 



initializes a sequence of Read 
operations for records with a 
specific byte or character string 
key having a given prefix 
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LOCKING 



Table 7-10 describes Locking operations. 



TRANSACTIONS 

Table 7-11 describes Transaction operations. 



Table 7-10. Locking Operations 



Operation 

HoldlSAMDataSet 
HoldlSAMRecord 

ReleaselSAMDataSet 

ReleaselSAMRecord 



Description 

locks an ISAM data set 

locks a record identified by its 
unique record identifier 

unlocks a locked data set without 
ending the current transaction 

unlocks a locked record without 
ending the current transaction 



Table 7-11. 
Operation 

BeginTransaction 
Commi tTr ansae t ion 

QueryTr ansae tionParams 
RollBackTransaction 



SetTransactionParams 



Transaction Operations 
Description 

marks the start of a transaction 

signifies a successful transaction 
completion; unlocks all records and 
data sets locked by the application 

accesses parameters associated with 
transactions for the application 

signifies the unsuccessful com- 
pletion of a transaction; unlocks 
all records locked by the applica- 
tion (This operation does not undo 
any changes made to ISAM data 
sets . ) 

sets parameters associated with 
transactions for the application 
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Transaction-Related Constraints 



The constraints associated with each ISAM operation used 
during transaction processing are shown in table 7-12. 
These constraints do not apply to operations on data sets 
open for batch access (in administrator, batch modify, or 
batch read mode). 



Transaction Parameters Block 



The Transaction Parameters Block (refer to table 7-13) 
contains values that control transaction operations. The 
wTicksWait parameter specifies the maximum time an applica- 
tion can wait to lock a record or data set. The other 
parameters do not affect ISAM data set access. (For further 
information about the use of wTicksWait, refer to 
section 2 . ) 

You can examine these parameters with the 

QueryTransactionParams operation and change them with the 
SetTransactionParams operation. 



Table 7-12. Transaction-Related Constraints 



Must Be in 
Transaction 



Must Not Be 
in Transaction 



No Transaction 
Constraints 



CommitTransaction 
DeletelSAMRecord 
DeletelSAMRecordBy- 
Key 

GetlSAMRecordsHold 
HoldlSAMDataSet 
HoldlSAMRecord 
ModifylSAMRecord 
ModifylSAMRecordByKey 
NormalizelSAMStatus 
ReadlSAMRecordByUri- 
Hold 

ReadNextlSAMRecord- 
Hold 



BeginTr ansae t ion 



CloselSAM 

CreatelSAM* 

DeletelSAM** 

GetlSAMRecords 

ISAMRequest 

OpenlSAM 

QueryTransaction- 
Params 
ReadlSAMRecordByUri 
ReadNextl SAMRecord 
ReadUniquelSAMRecord 
RenamelSAM** 
RollBackTransaction 
SetlSAMProtection** 



* Not applicable. A data set is not open when you create it. 

**Not applicable. A data set must be open in administrator 
mode to use this operation. 



5022247 



7-11 



Table 7-12. Transaction-Related Constraints (Cont) 



Must Be in 
Transaction 

ReadUniquelSAMRecord- 
Hold 

ReleaselSAMDataSet 

ReleaselSAMRecord 

StorelSAMRecord 



Must Not Be 
in Transaction 



No Transaction 
Constraints 

SetTr ansae tionParams 
SetUpISAMIteration- 

Limits 
SetUpISAMIteration- 

Pref ix 



Table 7-13. Transaction Parameters Block Format 

Offset Length Parameter Description 

0 2 wTxcksWait A word specifying the 

maximum number of 0.1- 
second ticks that a request 
waits when it tries to lock 
a record or data set (The 
default value is 100.) 



5 1 Reserved 

6 * Reserved 

ISAM SERVICE ACCESS 



Padding returned as 0 
(null) 

The asterisk indicates that 
it is for expansion and not 
required at present. 



Table 7-14 describes ISAM service access operations and how 
to use single-user ISAM. 

An application initializes single-user ISAM by calling the 
LoadSingleUserlSAM operation. The single-user ISAM server 
does not inform BTOS that ISAM is serving requests. 
Instead, the application builds request blocks and sends the 
request directly to ISAM using the BTOS Send operation 
rather than the BTOS Request operation. 
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ISAM sends the requests back using the BTOS Send operation 
instead of the BTOS Respond operation. 



Single-user ISAM requires the same amount of memory as 
multiuser ISAM installed for a single user. (Refer to 
section 1 for memory requirements information.) When you 
invoke the LoadSingleUserlSAM operation, ISAM allocates this 
memory as short-lived memory from the unallocated memory 
pool available to the application. 



USING EITHER MULTIUSER OR SINGLE-USER ISAM 



You can write an application to use either multiuser ISAM or 
single-user ISAM. By incorporating calls to both multiuser 
and single-user ISAM, an application is not dependent on 
multiuser ISAM server installation. 

The application calls the Vorif yMultiUserlSAM operation to 
check if multiuser ISAM is available. If it is, a status 
code of 0 (OK) returns, and the application uses multiuser 
ISAM. If any other status code returns, the application 
calls the LoadSingleUserlSAM operation to load single-user 
ISAM . 



Table 7-15 describes operations and asynchronous requests 
versus procedural requests. 



MEMORY USAGE 



ASYNCHRONOUS REQUESTS 



Table 7-14. 



ISAM Service Access 



Operations 



Description 



LoadSingleUserlSAM 



loads ISAM as a task and initializes 
communications with ISAM 



Ver if yMultiUserlSAM 



establishes whether or not multi- 
user access to ISAM is available on 
the standalone, cluster, or master 
workstation 
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Table 7-15. Asynchronous Requests 



Operations 



Description 



ISAMRequest 



issues an ISAM request and returns 
without waiting for request 
completion 



NormalizelSAMStatus 



ensures the validity of a status 
block returned by an asynchronous 
ISAM operation 



You can indirectly access ISAM system services by a 
procedural interface, or directly access them by the 
ISAMRequest, Wait, and NormalizelSAMStatus operations. 

Using the procedural interface is easier because it auto- 
matically performs most necessary housekeeping and issues 
the ISAMRequest and Wait operations. 

Using the ISAMRequest, Wait, and NormalizelSAMStatus 
operations enables applications to run more quickly and 
efficiently because there is a greater degree of overlap 
between processing by ISAM and computation by the 
application. 

Only one ISAM operation should be outstanding at a time 
because the order in which ISAM performs the operations is 
undefined. Overlapping certain operations can cause 
problems (for example, doing a CommitTransaction operation 
while a Modif ylSAMRecord operation is pending). 

When using asynchronous requests, the NormalizelSAMStatus 
operation must follow the Wait operation. Otherwise, the 
values in the status block can be invalid. 



The following information presents all ISAM procedures in 
alphabetical order. 



BeginTransaction Procedure 

The BeginTransaction procedure marks the start of a trans- 
action for the application. The transaction ends when the 



PROCEDURE DEFINITIONS 
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application uses either a CommitTransaction or a 
RollBackTransaction operation. 

You cannot call BeginTransaction from within a transaction. 
BeginTransaction is an object module procedure. 

The procedural interface is: 

Begintransaction (pStatusBlockRet): ErcType 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 



CloselSAM Procedure 



The CloselSAM procedure closes and releases all resources 
associated with an open data set. An ISAM handle for the 
closed data set is not valid after an application calls this 
procedure. If an application opens the same data set more 
than once, CloselSAM releases all records which were held 
for the data set, regardless of the handle used. CloselSAM 
is an object module procedure. 

The procedural interface is: 

CloselSAM (ISAMHandle, pStatusBlockRet): ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 



CommitTransaction Procedure 

The CommitTransaction procedure signifies the successful 
completion of a transaction and unlocks all records and data 
sets locked by the application. 

You can use CommitTransaction only in a transaction. 
CommitTransaction is an object module procedure. 

The procedural interface is: 

CommitTransaction (pStatusBlockRet): ErcType 
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pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 



CreatelSAM Procedure 



The CreatelSAM service defines the index structure of a data 
set and creates a new empty data set with the specified 
structure. The parameters supplied enable the application 
program to locate the data store and index files on 
different volumes and to control the allocation of disk 
sectors for the two files independently. 

The procedural interface is: 

CreatelSAM (pbFileSpecDataStoreFile, 
cbFileSpecDataStoreFile, 
pbPasswordDataStoreFileCreate, 
cbPasswordDataStoreFileCreate , 
pbFileSpecIndexFile, cbFileSpedndexFile, 
pbPasswordlndexFileCreate, 
cbPasswordlndexFileCreate, pISAMDesc, 
sISAMDesc, pStatusBlockRet): ErcType 

pbFileSpecDataStoreFile and CbFileSpecDataStoreFile describe 
a file specification for the data store file of the new data 
set . 

pbPasswordDataStoreFileCreate and 

CbPasswordDataStoreFileCreate describe a password used to 
create the data store file of the new data set. 

pbFileSpecIndexFile and cbFileSpedndexFile describe a file 
specification for the index file of the new data set. If 
cbFileSpedndexFile is 0, the file specification for the 
index is derived from the file specification for the data 
store file. 

ISAM copies the file specification defined by 
pbPasswordDataStoreFileCreate and 

CbPasswordDataStoreFileCreate, then replaces the suffix 
beginning with the period character with the 
characters .Ind. 

For example, if the file specification for the data store 
file is [vol] <dir>DataSet . Isam, the file specification for 
the index file is [vol] <dir >DataSet . Ind . 

pbPasswordlndexFileCreate and cbPasswordlndexFileCreate 
describe a password used to create the index file of the new 
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data set. If the name of the index file is null, these two 
parameters are ignored. The system uses the password 
specified for the data store file to create the index file 
as well. 

pISAMDesc and sISAMDesc describe a memory area containing an 
ISAM Description Block which has the structure shown in 
table 7-4. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-16 details the CreatelSAM request block. 



Table 7-16. CreatelSAM Request Block 

Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


0 


2 


nReqPbCb 


1 


5 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


79 


12 


pbFileSpecDataStorcFile 


4 




16 


cbFileSpecDataStoroFile 


2 




18 


pbPasswordDataStore- 








FileCreate 


4 




22 


cbPasswordDataStore- 








FileCreate 


2 




24 


pbFileSpecIndexFile 


4 




28 


cbFileSpecIndexFile 


2 




30 


pbPasswordlndexFile- 








Create 


4 




34 


cbPasswordlndexFile- 








Create 


2 




36 


pISAMDesc 


4 




40 


sISAMDesc 


2 




42 


pStatusBlockRet 


4 




46 


sStatusBlock 


2 


4 
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DeletelSAM Procedure 



The DeletelSAM service deletes the files of a data set, 
thereby destroying all information in the data set. The 
data set must be opened in administrator mode. 

The procedural interface is: 

DeletelSAM (iSAMHandle, pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-17 describes the DeletelSAM request block. 



DeletelSAMRecord Procedure 



The DeletelSAMRecord service removes a record from a data 
set. You must open the data set in modify mode to change 
it. The disk space occupied by the record is available for 
a subsequent StorelSAMRecord operation. ISAM automatically 
removes all keys for the record from the indexes of the data 
set and destroys data in the record. 



Table 7-17. DeletelSAM Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
18 



sCntlnfo 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
4 
2 



80 



4 



2 
0 
1 
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If the data set is in transaction mode, you can call 
DeletelSAMRecord only from within a transaction and when the 
record to be deleted is locked. 



The procedural interface is: 



DeletelSAMRecord (ISAMHandle, uriRecord, 

pStatusBlockRet ) : ErcType 



ISAMHandle the ISAM handle that identifies the open data 
set. 

uriRecord is the unique record identifier of the deleted 
record. UriRecord is the value returned by a previous Read 
operation. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-18 describes the DeletelSAMRecord request block. 



Table 7-18. DeletelSAMRecord Request Block 



Offset 



Parameter 



Size 
(bytes ) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
18 
22 



sCntlnfo 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

uriRecord 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
4 
4 
2 



81 



4 



6 
0 
1 
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DeletelSAMRecordByKey Procedure 



The DeletelSAMRecordByKey service removes a record from a 
data set. The data set must be open in modify mode to 
change it. DeletelSAMRecordByKey, however, uses a unique 
key to identify the record instead of a unique record 
identifier . 

The disk space occupied by the record is available for a 
subsequent StorelSAMRecord operation. ISAM automatically 
removes all Keys for the record from the indexes of the data 
set and destroys all data in the record. 

If the data set is open in a transaction mode, you can call 
DeletelSAMRecordByKey only from within a transaction. The 
record to be deleted does not have to be locked. 
DeletelSAMRecordByKey locks the record before deleting it. 

The procedural interface is: 

DeletelSAMRecordByKey (ISAMHandle, ilndex, pKey, sKey, 

pUriRecordRet, pStatusBlockRet ) : 
ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

ilndex identifies the index used. (The indexes are numbered 
from 0 in the order specified in CreatelSAM.) 

pKey and sKey describe the memory area containing the key 
that identifies the record to be deleted. sKey must be the 
correct length, in bytes, of the key for index ilndex. 

pUriRecordRet is the memory address of the 4-byte structure 
where the unique record identifier for the record to be 
deleted is returned. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-19 details the DeletelSAMRecordByKey request block. 



GetlSAMRecords and GetlSAMRecordsHold Procedures 

With a single call to ISAM, the GetlSAMRecords service reads 
several records or unique record identifiers in key order 
from a data set. Records are returned in key order for the 
current iteration. If there are no more records for the 
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Table 7-19. DeletelSAMRecordByKey Request Block 



Size 



Offset 


Parameter 


(bytes ) 


Co n t e n t s 




e n +■ T n 4" /"\ 


9 

Z 


A 


9 
z 


n T? on O V\f" l V» 


1 
X 


1 

X 


-3 
J 


m O v\DV\^l^ 

llKesprDLD 


X 


9 


ft 


ussrNuiu 


9 

z 




O 


CACIlKcbp 


z 




8 


ercRet 


2 




10 


rqCode 


2 


199 


12 


ISAMHandle 


2 




14 


ilndex 


2 




16 




4 




20 


sKey 


2 




22 


pUriRecordRet 


4 




26 


sUriRecord 


2 


4 


28 


pStatusBlockRet 


4 




32 


sStatusBlock 


2 


4 


iteration, 


the status code 3127 


(No more 


records ) i s 



returned. 

The GetlSAMRecordsHold service is identical to 
GetlSAMRecords, except GetlSAMRecordsHold also locks the 
records read (or those that have unique record identifiers 
returned). When records are read, each one is locked. If 
unique record identifiers are returned, the record 
identified by each unique record identifier is locked. 

If you use GetlSAMRecordsHold, none of the accessed records 
can be accessed by other applications until you release 
them, usually by a subsequent CommitTransaction operation. 

The GetlSAMRecords and GetlSAMRecordsHold operations return 
as many records (or unique record identifiers) in sequence 
as possible, subject to the following constraints: 

o The buffer capacity is not exceeded. 

e The range specified for the current iteration is 
not exceeded. 

• Records locked by other applications are not read. 

For example, a particular GetlSAMRecords operation reads 
4-byte unique record identifiers and 40-byte records into a 
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500-byte buffer. The buffer can contain up to 11 records 
and unique record identifiers (440 +44). If the seventh 
record in the sequence is locked by another application, the 
GetlSAMRecords operation returns only the first six records 
and unique record identifiers. 

If an application uses this service to get records from a 
remote workstation, it can encounter the status code 45 
(Request block too large). This occurs when you specify a 
buffer size too large for the operating system to accom- 
modate. You can either decrease the buffer size or increase 
line and transmission buffers at a system build. 

If GetlSAMRecords is called to read only unique record 
identifiers, it returns unique record identifiers for locked 
records. Applications can "skip over" records locked by 
other applications. 

If the data set is open in a transaction mode, the 
application does not have to be in a transaction before 
calling GetlSAMRecords, but it must be in a transaction 
before calling GetlSAMRecordsHold . 

The procedural interface is: 

GetlSAMRecords and 

GetlSAMRecordsHold (ISAMHandle, f ReadRecords , pBuffer, 

sBuffer, pCRecordsReadRet , 
pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

fReadRecords specifies whether records and unique record 
identifiers are returned. fReadRecords is FALSE if only 
unique record identifiers are returned, and TRUE if records 
are returned also. 

pBuffer and sBuffer describe the memory area into which the 
unique record identifiers and records are to be read. 

If only unique record identifiers are returned (fReadRecords 
is FALSE), the record identifiers are packed into the buffer 
without padding. If both unique record identifiers and 
records are returned (fReadRecords is TRUE), the unique 
record identifiers and records are packed together into the 
buffer without padding. Each record and its record iden- 
tifier are packed as a pair with the record identifier 
preceding the record. 
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For example, table 7-21 shows the buffer structure after 
three 46-byte records are read. 

pCRecordsReadRet is the memory address of the word where the 

number of unique record identifiers and/or records read is 
returned. 

pStatusBlockRet. is the memory address of the status block 

into which the status codes from the operation are returned. 

Table 7-20 describes the GetlSAMRecords and 
GetlSAMRecordsHold request block. 



Table 7-20. GetlSAMRecords and GetlSAMRecordsHold 



Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
15 
16 
20 
22 
26 
28 
32 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

f ReadRecords 

reserved 

pBuf f er 

sBuf f er 

pCRecordsReadRet 
sCRecordsRead 
pStatusBlockRet 
sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
1 
1 
4 
2 
4 
2 
4 
2 



4 



4 

0 
3 



0 



2 



* 



♦GetlSAMRecords = 82; GetlSAMRecordsHold = 0. 
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Table 



7 



-21. 



Buffer Structure for GetlSAMRecords and 
GetlSAMRecordsHold when Records are Read 
(46-Byte Records) 



Offset 

0 
4 



Description 



Size 
(bytes) 



50 
54 
100 
104 



Record identifier of record 1 
Record 1 

Record identifier of record 2 
Record 2 

Record identifier of record 3 
Record 3 



4 
46 

4 
46 

4 
46 



HoldlSAMDataSet Procedure 



The HoldlSAMDataSet service locks an open data set. If the 
data set is opened in a transaction mode, HoldlSAMDataSet 
can be called only from within a transaction. 

The procedural interface is: 

HoldlSAMDataSet (ISAMHandle, fLockRecords , pStatusBlockRet ) : 
ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

fLockRecords specifies whether a subsequent 

ReleaselSAMDataSet operation unlocks the data set's locked 
records as well as the data set itself. fLockRecords is 
either TRUE or FALSE. 

If fLockRecords is TRUE and if the data set is unlocked by a 
subsequent ReleaselSAMDataSet operation, locked records in 
the data set continue to be locked. 

If fLockRecords is FALSE and if the data set is unlocked by 
the ReleaselSAMDataSet operation, all records in the data 
set are unlocked. 
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For example, data set X has five records and the following 
events occur: 



1. Record 1 is locked (for example, with the 
HoldlSAMRecord operation). 

2. ■ Data set X is locked with the HoldlSAMDataSet 

operation. 

3. Record 2 is locked (for example, with the 
ReadNextlSAMRecordHold operation) . 

4. Data set X is unlocked with the ReleaselSAMDataSet 
operation. 

If fLockRecords is TRUE in step 2, Record 1 and Record 2 
remain locked after step 4. If fLockRecords is FALSE in 
step 2, Record 1 and Record 2 are unlocked after step 4. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-22 describes the HoldlSAMDataSet request block. 



Table 7-22. HoldlSAMDataSet Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
15 
16 
20 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

fLockRecords 

reserved 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
1 
1 
4 
2 



205 



4 



4 
0 
1 



0 
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HoldlSAMRecord Procedure 



The HoldlSAMRecord service locks a record identified by its 
unique record identifier. The record identifier is not 
checked for validity by HoldlSAMRecord. 

If the data set is opened in a transaction mode, 
HoldlSAMRecord can be called only from within a transaction. 

The procedural interface is 

HoldlSAMRecord (iSAMHandle, uriRecord, 

pStatusBlockRet) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

uriRecord is the unique record identifier of the record to 
be locked. uriRecord is usually the value returned by a 
previous Read operation. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-23 details the HoldlSAMRecord request block. 



Table 7-23. HoldlSAMRecord Request Block 



Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


6 


2 


nReqPbCb 


1 


0 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


130 


12 


ISAMHandle 


2 




14 


uriRecord 


4 




18 


pStatusBlockRet 


4 




22 


sStatusBlock 


2 


4 
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ISAMRequest Procedure 



The ISAMRequest procedure issues an ISAM request and returns 
without waiting for the request to be completed. 

This operation is used to issue asynchronous ISAM requests 
in both multiuser and single-user ISAM. For multiuser ISAM, 
ISAMRequest uses the Request operation, but for single-user 
ISAM, ISAMRequest uses the Send operation. ISAMRequest 
allows applications to issue asynchronous requests without 
regard to whether multiuser or single-user ISAM is being ( 
used. (For more information on the Request and Send 
operations, refer to the B 20 Systems Operating System 
(BTQS) Reference Manual . ) 

ISAMRequest is an object module procedure. 

The procedural interface is: 

ISAMRequest (pRq): ErcType 

pRq is the memory address of the request block specifying 
the ISAM. 



LoadSingleUserlSAM Procedure 



The LoadSingleUserlSAM procedure loads ISAM as a task and 
initializes communication with ISAM. The ISAM task is 
loaded into short-lived memory allocated from the pool of 
unallocated memory pool available. to the application. 

LoadSingleUserlSAM is an object module procedure. 

The procedural interface is: 

LoadSingleUserlSAM (pbFileSpecRunFile , 

cbFileSpecRunFile, pbPwRunFile, 
cbPwRunFile, pbConf igFile , 
cbConf igFile, pbPwConf igFile, 
cbPwConf igFile, pStatusBlockRet ) : 
ercType 

pbFileSpecRunFile and CbFileSpecRunFile describe the memory 
area containing the ISAM run file name. If 
CbFileSpecRunFile is 0, the run file name defaults to 
[Sys] <Sys>ISAMServer .Run. 



5022247 



7-27 



pbPwRunFile and cbPwRunFile describe the memory area 
containing the password used to open the ISAM run file. 

pbConfigFile and cbConfigFrle describe the memory area 
containing the ISAM configuration file name. If 
cbConfigFile is 0, the configuration file name defaults to 
[Sys]<Sys>ISAM.Conf ig. 

pbPwConf igFile and cbPwConf igFile describe the memory area 
containing the password used to open the ISAM configuration 
file. 

pStatusBlockRet is the memory address of the status block 
into which the status from the operation are returned. 



ModifylSAMRecord Procedure 



The ModifylSAMRecord service modifies an existing record in 
a data set and updates all indexes. The record is identi- 
fied by its unique record identifier. 

If any key is changed, the record entry for the old value is 
removed from the index and the record is reindexed under the 
new value. If the new value of the key duplicates an 
existing key for the same index in another record and 
duplicates are not allowed for that index, the record is not 
modified, the index is not changed, and status code 3118 
(Duplicate key) is returned. 

The data set must be open for modification. The record 
remains locked after modification. 



If the data set is open in a transaction mode, 
ModifylSAMRecord can be called only from within a 
transaction. 



The procedural interface is: 



ModifylSAMRecord (ISAMHandle, uriRecord, pRecord, 

sRecord, pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 



uriRecord is the unique record identifier of the record to 
be modified. uriRecord is usually the value returned by a 
previous Read operation. 
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pRecord and sRecord describe the memory area containing the 
record to be written. sRecord must be equal to the record 
size for the data set. 

pStatusBlocKRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-24 details the ModifylSAMRecord Request Block. 



ModifylSAMRecordByKey Procedure 

The ModifylSAMRecordByKey service modifies a data set record 
and updates all indexes. It uses a unique key to identify 
the record instead of a record identifier. 

If any key is changed, the record is removed from the index 
under the old value of the key and reindexed under the new 
value. If the new value of the key duplicates an existing 
key for the same index in another record, but duplicates are 
not allowed for that index, the record is not modified, the 
index is not changed, and status code 3118 (Duplicate key) 
is returned. 



Table 7-24. ModifylSAMRecord Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
18 
22 
24 
28 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

uriRecord 

pRecord 

sRecord 

pStatusBlockRet 
sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
4 
4 
2 
4 
2 



6 
1 
1 



84 



4 
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The parameters for this operation include the index and the 
new record contents, but not a separate key for the record. 
The key used to' identify the record is taken from the record 
itself. 

For example, to change the salary of employee 150 in the 
Employee data set from $34,000 to $37,500, ilndex is 
specified as 0. (empNo is index 0, a unique key index.) 
ISAM extracts the empNo field, uses the empNo index to 
determine which record is to be modified and modifies the 
record. 

This service cannot be used to change the key being used to 
identify the record. 

The data set must be open for modification. 

If the data set is open in a transaction mode, 
ModifylSAMRecordByKey can be called only from within a 
transaction. The record to be modified need not be locked; 
ModifylSAMRecordByKey locks the record before modifying it. 

The procedural interface is: 

ModifylSAMRecordByKey (ISAMHandle, ilndex, pRecord, 

sRecord, pUriRecordRet , 
pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

ilndex identifies the index used. (The indexes are numbered 
from 0 in the order specified in CreatelSAM.) 

pRecord and sRecord describe the memory area containing the 
record to be modified. sRecord must be equal to the record 
size for the data set. 

pUriRecordRet is the memory address of the 4-byte structure 
where the unique record identifier of the modified record is 
returned . 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-25 describes the ModifylSAMRecordByKey request 
block. 
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Table 7-25. Modify ISAMRecordByKey Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
16 
20 
22 
26 
28 
32 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

ilndex 

pRecord 

sRecord 

pUriRecordRet 

sUriRecord 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
2 
4 
2 
4 
2 
4 
2 



4 
1 

2 



198 



2 



4 



NormalizelSAMStatus Procedure 

The NormalizelSAMStatus procedure ensures that both the 
ercRet field of the request equals the ere field of the 
status block and the ercDetail field of the status block is 
valid. 

An application must call NormalizelSAMStatus after 
asynchronous ISAM requests (issued by ISAMRequest) are 
completed. If not, the status block that the ISAM operation 
returns has undefined contents. 

The status code that NormalizelSAMStatus returns diagnoses 
problems encountered while normalizing the status block. In 
general, the status code returned differs from the ercRet 
field in the request block. 

For example, if an asynchronous Read operation returns 
status code 3127 (no more records) and a detail status of 0 
(OK), NormalizelSAMStatus ensures that the ercRet field in 
the request block matches the status block ere field and 
returns 0 (OK) . 

NormalizelSAMStatus is an object module procedure. 
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The procedural interface is: 

NormalizelSAMStatus (pRq): ErcType 
pRq is the memory address of the request block. 



OpenlSAM Procedure 

The OpenlSAM procedure opens an existing data set and 
returns an ISAM handle for it. The ISAM handle is used to 
refer to the data set in subsequent operations. OpenlSAM is 
an object module procedure. 

The procedural interface is: 

OpenlSAM (pISAMHandleRet , pbDataSetName, cbDataSetName, 
pbPassword, cbPassword, mode, sRecord, 
pStatusBlockRet ) : ErcType 

pISAMHandleRet is the memory address of the word into which 
the ISAM handle of the opened data set is returned. 

pbDataSetName and cbDataSetName describe the memory area 
containing the character string representing the name of the 
data set. 

pbPassword and cbPassword describe either the modify or read 
password for the opened data set, or a file system password 
that gives modify access to the data set files. If the mode 
is batch modify or transaction modify, you must supply the 
modify password. If the mode is batch read or transaction 
read, you can supply either password. If the mode is admin- 
istrator, you must supply a file system password. 

Mode specifies the mode in which the data set is opened as 
detailed in table 7-26. 

In these ASCII constants, the first character is the high- 
order byte, and the second character is the low-order byte. 
This is the reverse of the byte order of strings in the B 20 
programming languages. 

For further information regarding modes, refer to section 2. 

sRecord is the fixed-length record size for the data set. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 
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Table 7-26. Data Set Modes 



Value (ASCII) 



Mode 



ad 
bm 
br 
tm 
tr 



administrator 
batch modify 
batch read 
transaction modify 
transaction read 



QueryTransactionParams Procedure 

The QueryTransactionParams procedure retrieves the applica 
tion's current transaction parameters. (For more informa- 
tion, refer to Transaction Parameters Block, in this 
section . ) 

QueryTransactionParams is an object module procedure. 

The procedural interface 13 : 

QueryTransactionParams (pParamsRet, sParamsMax, 

pSParamsRet, pStatusBlockRet) : 
IircType 

pParamsRet and sParamsMax describe the memory area into 
which the transaction parameters are stored. The 
Transaction Parameters Block has the format shown in 
table 7-13. 

pSParamsRet is the memory address of a word into which the 
number of bytes retrieved are stored. The value stored in 
this word cannot exceed sParamsMax. 

pStatusBlockRet is the status block memory address xnto 
which the status codes from the operation are returned. 



ReadlSAMRecordByUri and ReadlSAMRecordByllriHold Procedures 

The ReadlSAMRecordByUri service reads a record identified by 
its unique record identifier. The ReadlSAMRecordByUriHold 
service is identical to ReadlSAMRecordByUri, except 
ReadlSAMRecordByUriHold also locks the record when it is 
read. 
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If the data set is open in a transaction mode, then 
ReadlSAMRecordByUriHold can be called only from within a 
transaction . 

The procedural interface is: 
ReadlSAMRecordByUri and 

ReadlSAMRecordByUriHold (ISAMHandle, uriRecord, 

pRecordRet, sRecord, 
pStatusBlockRet): ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

uriRecord is the unique record identifier of the record to 
be read. uriRecord is usually the value that a previous 
Read operation returns. 

pRecordRet and sRecord describe the memory area into which 
the record is read. sRecord must be equal to the record 
size for the data set. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-27 describes the ReadlSAMRecordByUri and 
ReadlSAMRecordByUriHold request block. 



Table 7-27. ReadlSAMRecordByUri and ReadlSAMRecordByUriHold 
Request Block 

Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


6 


2 


nReqPbCb 


1 


0 


3 


nRespPbCb 


1 


2 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


* 


12 


ISAMHandle 


2 




14 


uriRecord 


4 




18 


pRecordRet 


4 




22 


sRecord 


2 




24 


pStatusBlockRet 


4 




28 


sStatusBlock 


2 


4 



♦ReadlSAMRecordByUri = 86; ReadlSAMRecordByUriHold = 131. 
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ReadNextlSAMRecord and ReadNextlSAMRecordHold Procedures 



The ReadNextlSAMRecord service reads the next record in key 
order from a data set. The unique record identifier of the 
record is returned. The ReadNextlSAMRecordHold service is 
identical to ReadNextlSAMRecord, except it also locks the 
record when it is read. 

If the data set is open in a transaction mode, 
ReadNextlSAMRecordHold can be called only from within a 
transaction . 

The procedural interface is: 
ReadNextlSAMRecord and 

ReadNextlSAMRecordHold (iSAMHandle, pRecordRet, 

sRecord, pUriRecordRet, 
pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

pRecordRet and sRecord describe the memory area into which 
the record is read. sRecord must be equal to the record 
size for the data set. 

pUriRecordRet is the memory address of the 4-byte structure 
into which the unique record identifier of the record is 
returned . 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-28 describes the ReadNextlSAMRecord and 
ReadNextlSAMRecordHold request block. 



ReadUniquelSAMRecord and ReadUniquelSAMRecordHold Procedures 

The ReadUniquelSAMRecord service reads a record uniquely 
identified by a given key from a data set. Duplicates are 
not allowed for the index used, so that the key appears at 
most in one record of the data set. 

The ReadUniquelSAMRecordHold service is identical to 
ReadUniquelSAMRecord, except ReadUniquelSAMRecordHold also 
locks the record. If the data set is open in a transaction 
mode, ReadUniquelSAMRecordHold can be called only from 
within a transaction. 
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Table 7-28. ReadNextlSAMRecord and ReadNextlSAMRecordHold 
Request: Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
18 
20 
24 
26 
30 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

pRecordRet 

sRecord 

pUriRecordRet 

sUriRecord 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
4 
2 
4 
2 
4 
2 



4 



4 



2 
0 
3 



* 



♦ReadNextlSAMRecord = 87; ReadNextlSAMRecordHold = 13 2. 

The procedural interface is: 
ReadUniquelSAMRecord and 

ReadUniquelSAMRecordHold (ISAMHandle, ilndex, pKey, 



ISAMHandle is the ISAM handle that identifies the open data 
set. 

ilndex identifies the index used. (The indexes are numbered 
from 0 in the order specified in CreatelSAM.) 

pKey and sKey describe the memory area containing the unique 
key that identifies the record to be read. sKey must be the 
correct length, in bytes, of keys for the index, ilndex. 

pRecordRet and sRecord describe the memory area into which 

the record is read. sRecord must be equal to the record 
size for the data set. 

pUriRecordRet is the memory address of the 4-byte structure 

into which the unique record identifier of the record is 
returned. 



sKey, pRecordRet, sRecord, 
pUriRecordRet , 
pStatusBlockRet): ErcType 
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pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-29 details the ReadUniquelSAMRecord and 
ReadUniquelSAMRecordHold request block. 



ReleaselSAMDataSet Procedure 

The ReleaselSAMDataSet service releases a locked data set 
without ending the current transaction. 



NOTE 

Use this operation with care, since 
other applications can hold and even 
modify the released data set before the 
transaction is ended. 



Table 7-29. ReadUniquelSAMRecord and 

ReadUniquelSAMRecordHold Request 
Block 

Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


4 


2 


nReqPbCb 


1 


1 


3 


nRespPbCb 


1 


3 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


* 


12 


ISAMHandle 


2 




14 


ilndex 


2 




16 


pKey 


4 




20 


sKey 


2 




22 


pRecordRet 


4 




26 


sRecord 


2 




28 


pUriRecordRet 


4 




32 


sUriRecord 


2 


4 


34 


pStatusBlockRet 


4 




38 


sStatusBlock 


2 


4 



♦ReadUniquelSAMRecord = 88; ReadUniquelSAMRecordHold = 133. 
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If the data set is open in a transaction mode, 
ReleaselSAMDataSet can be called only from within a 
transaction. 

The procedural interface is: 

ReleaselSAMDataSet (ISAMHandle, pStatusBlockRet): 

ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-30 describes the ReleaselSAMDataSet request block. 



ReleaselSAMRecord Procedure 

The ReleaselSAMRecord service releases a locked record 
without ending the current transaction. 



NOTE 



Other applications can hold and even 
modify the released record before the 
transaction ends. 



Table 7-30. ReleaselSAMDataSet Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
18 



sCntlnfo 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

pStatusBlockRet 

sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
4 
2 



206 



2 
0 
1 



4 
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If the data set is open in a transaction mode, 
ReleaselSAMRecord can be called only from within a 
transaction . 

The procedural interface is: 

ReleaselSAMRecord (ISAMHandle, uriRecord, 

pStatusBlockRet): ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

uriRecord is the unique record identifier for the record to 
be released. uriRecord is usually the value returned by a 
previous Read operation. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-31 describes the ReleaselSAMRecord request block. 



RenamelSAM Procedure 

The RenamelSAM service changes the name of a data set by 
changing the name of both the data store and index files. 
It is invalid to rename only one of the two files. 

RenamelSAM uses two invocations of the BTOS RenameFile 
operation; one to change the data store file name and one to 
change the index file name. 



Table 7-31. ReleaselSAMRecord Request Block 



Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


6 


2 


nReqPbCb 


1 


0 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


134 


12 


ISAMHandle 


2 




14 


uriRecord 


4 




18 


pStatusBlockRet 


4 




22 


sStatusBlock 


2 


4 
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There are certain RenameFile operations that are invalid, 
such as renaming a file from one volume to another, or 
renaming a file using an incorrect password. If a 
RenamelSAM operation is attempted where one of the two 
required BTOS RenameFile operations is invalid, ISAM detects 
the error and renames the data set by using a valid name for 
both the data store and index file. One or both of the 
files, in this case, can retain the original name. 

You must open the data set in administrator mode. 

The procedural interface is: 

RenamelSAM (ISAMHandle, pbFileSpecDataStoreFile , 
cbFileSpecDataStoreFile, 
pbPasswordDataStoreFileRename , 
cbPasswordDataStoreFileRename, 
pbFileSpecIndexFile, cbFileSpecIndexFile , 
pbPasswordlndexFileRename, 

cbPasswordlndexFileRename, pStatusBlockRet ) : 
ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

pbFileSpecDataStoreFile and cbFileSpecDataStoreFile describe 
the file specification for the new name of the data store 
file for the data set. 

pbPasswordDataStoreFileRename and 

cbPasswordDataStoreFileRename describe the password used 
when renaming the data store file for the data set. 

pbFileSpecIndexFile and cbFileSpecIndexFile describe a file 
specification for the new index file name for the data set. 
If cbFileSpecIndexFile is 0, the file specification for the 
index is derived from the file specification for the data 
store file. ISAM copies the file specification defined by 
pbPasswordDataStoreFile and cbPasswordDataStoreFile. Then 
ISAM replaces the suffix (beginning with the period 
character) with the characters .Ind. 

For example, if the file specification for the data store 
file is [vol] <dir>DataSet . Isam,. the file specification for 
the index file is [vol] <dir >DataSet . Ind . 

pbPasswordlndexFileRename and cbPasswordlndexFileRename 
describe the password used when renaming the data set index 
file. If the index file name is null, these two parameters 
are ignored and the password specified for the data store 
file is also used to create the index file. 
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pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-32 details the RenamelSAM request block. 



RollBackTransaction Procedure 



The RollBackTransaction procedure signifies the unsuccessful 
end of a transaction and unlocks all records and data sets 
locked by the application. 

Although you can call RollBackTransaction, it is effective 
only when the calling application is in a transaction. 

RollBackTransaction is an object module procedure. 

The procedural interface is: 

RollBackTransaction (pStatusBlockRet): ErcType 



Table 7-32. RenamelSAM Request Block 

Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnf o 


2 


2 


2 


nReqPbCb 


1 


4 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


89 


12 


ISAMHandle 


2 




14 


pbFileSpecDataStoreFile 


4 




18 


cbFileSpecDataStoreFile 


2 




20 


pbPasswordDataStore- 








FileRename 


4 




24 


cbPasswordDataStore- 








FileRename 


2 




26 


pbFileSpecIndexFile 


4 




30 


cbFileSpecIndexFile 


2 




32 


pbPasswordlndexFile- 








Rename 


4 




36 


cbPasswordlndexFile- 








Rename 


2 




38 


pStatusBlockRet 


4 




42 


sStatusBlock 


2 


4 
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pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 



SetlSAMProtection Procedure 

The SetlSAMProtection service changes the passwords that 
allow an application to gain access to an open data set. 

SetlSAMProtection does not change the file system passwords 
for the data set files. You use the Executive SET 
PROTECTION command to change these passwords. You must open 
the data set in administrator mode. 

The procedural interface is: 

SetlSAMProtection (ISAMHandle, pbPasswordOpenRead, 
cbPasswordOpenRead, 
pbPasswordOpenModify , 
cbPasswordOpenModify, 
pStatusBlockRet): ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set . 

pbPasswordOpenRead and cbPasswordOpenRead describe the 
password that opens the data set for reading in either batch 
read or transaction read modes. The password cannot be 
longer than 12 bytes. 

pbPasswordOpenModify and cbPasswordOpenModify describe the 
password that opens the data set for modification in either 
batch modify or transaction modify modes. This password can 
also be used to open the data set for reading in batch read 
or transaction read modes. The password cannot be longer 
than 12 bytes. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 

Table 7-33 describes the SetlSAMProtection request block. 



SetTransactionParams Procedure 

The SetTransactionParams procedure sets the application's 
current transaction parameters. (For more information, 
refer to Transaction Parameters Block, in this section. ) 
SetTransactionParams is an object module procedure. 
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Table 7-33. SetlSAMProtection Request: Block 



Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnfo 


2 


2 


2 


nReqPbCb 


1 


2 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


90 


12 


ISAMHandle 


2 




14 


pbPasswordOpenRead 


4 




18 


cbPasswordOpenRead 


2 




20 


pbPasswordOpenModif y 


4 




24 


cbPa s swor dOpe nModi f y 


2 




26 


pStatusBlockRet 


4 




30 


sStatusBlock 


2 


4 



The procedural interface is: 

SetTransactionParams (pParams, sParams, 

pStatusBlockRet ) : ErcType 

pParams and sParams describe the memory area containing the 
transaction parameters to be set. The Transaction 
Parameters Block has the format shown in table 7-13. If 
sParams is less than the length of the Transaction 
Parameters Block: 

1. The supplied block must not include a partial 
field at the end. 

2. Only parameters included in the block are changed. 

pStatusBlocKRet is the memory address of the status block 
into which the status codes from the operation are returned. 



SetUplSAMIterationLimits Procedure 

The SetUplSAMIterationLimits service initializes a sequence 
of Read operations for records that have keys for a 
specified index within a given range. Subsequent calls to 
GetlSAMRecords(Hold) and ReadNextlSAMRecord(Hold) operations 
read each record that has a key value within the range. 
Records are read in key value order. 
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If the index is not defined to include null values 
(binary O's), records with null keys are not read. 

The procedural interface is: 

SetUpISAMIterationLimits (ISAMHandle, ilndex, 

matchKind, pKeyl , sKeyl, 
pKey2, sKey2, 
pStatusBlockRet ) : ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

ilndex identifies the index used. (The indexes are numbered 
from 0 in the order specified in CreatelSAM.) 

matchKind specifies which records are retrieved according to 
the following: 

0 all records, regardless of their key values (keyl 
and key2 are both ignored; sKeyl and sKey2 should 
be 0. ) 

1 all records containing a key less than keyl (key2 
is ignored, and sKey2 should be 0.) 

2 all records containing a key less than or equal to 
keyl (key2 is ignored, and sKey2 should be 0.) 

3 all records containing a key equal to keyl. (key2 
is ignored, and sKey2 should be 0.) 

4 all records containing a key greater than or equal 
to keyl. (key2 is ignored, and sKey2 should be 0.) 

5 all records containing a key greater than keyl 
(key2 is ignored, and sKey2 should be 0.) 

6 all records containing a key greater than keyl, 
but less than key2 

7 all records containing a key greater than or equal 
to keyl, but less than key2 

8 all records containing a key greater than or equal 
to keyl, but less than or equal to key2 

9 all records containing a key greater than keyl, 
but less than or equal to key2 
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pKeyl and sKeyl describe the memory area containing a Key 
record. The key affects the set of records that subsequent 
read operations return (see matchKind for further 
information). 

pKey2 and sKey2 describe the memory area containing a Key 
record. The key affects the set of records that subsequent 
read operations return (see matchKind for further 
information ) . 

pStatusBlockRet is the status block memory address into 
which the status codes from the operation are returned. 

Table 7-34 describes the SetUpISAMIterationLimits request 
block. 



SetUplSAMIterationPrefix Procedure 

The SetUplSAMIterationPrefix service initializes a sequence 
of Read operations for records with keys for a specified 
index having a given prefix. Subsequent calls to 
GetlSAMRecords (Hold) and ReudNextlSAMRecord (Hold ) operations 



Table 7-34. SetUpISAMIterationLimits Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
16 
17 
18 
22 
24 
28 
30 
34 



sCntlnf o 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

ilndex 

matchKind 

reserved 

pKeyl 

sKeyl 

pKey2 

sKey2 

pStatusBlockRet 
sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
2 
1 
1 
4 
2 
4 
2 
4 
2 



6 
2 
1 



210 



0 



4 
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read each record for which the given key is a prefix of the 
key stored in the record. 

The index must contain either byte string or character 
string keys. 

If the index is not defined to include null values (binary 
O's), records with null keys are not read. 

The procedural interface is: 

SetUpISAMIterationPref ix (ISAMHandle, ilndex, pKey, 

sKey, pStatusBlockRet ) : 
ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

ilndex identifies the index used. (The indexes are numbered 
from 0 in the order specified in CreatelSAM.) 

pKey and sKey describe the memory area containing the key. 
sKey must be no larger than the length of the keys for 
index, ilndex. 

pStatusBlockRet is the status block memory address into 
which the status codes from the operation are returned. 

Table 7-35 details the SetUpISAMIterationPref ix request 
block . 



Table 7-35. SetUpISAMIterationPref ix Request Block 



Offset 



Parameter 



Size 
(bytes) 



Contents 



0 
2 
3 
4 
6 
8 
10 
12 
14 
16 
20 
22 
26 



sCntlnfo 

nReqPbCb 

nRespPbCb 

userNum 

exchResp 

ercRet 

rqCode 

ISAMHandle 

ilndex 

pKey 

sKey 

pStatusBlockRet 
sStatusBlock 



2 
1 
1 
2 
2 
2 
2 
2 
2 
4 
2 
4 
2 



4 
1 
1 



92 



4 
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StorelSAMRecord Procedure 



The StorelSAMRecord service creates a new record in a data 
set. If necessary, the length of the data store file for 
the data set is increased to accommodate the new record. 

The indexes are updated as required to reflect the presence 
of the new record. If the value of the new key duplicates 
an existing key in the same index, and duplicates are not 
allowed for that index, the record is not stored and the 
status code 3118 (duplicate key) is returned. 

The data set must be open for modification. 

If the data set is open in transaction mode, StorelSAMRecord 
can be called only from within a transaction. The created 
record is locked after StorelSAMRecord is called. 

The procedural interface is: 

StorelSAMRecord (iSAMUandle, pRecord, sRecord, 

pUriRecordRet , pStatusBlockRet ) : 
ErcType 

ISAMHandle is the ISAM handle that identifies the open data 
set. 

pRecord and sRecord describe the memory area containing the 
record to be written. sRecord must be equal to the record 
size for the data set. 

pUriRecordRet is the memory address of the 4-byte structure 
where the unique record identifier of the record to be 
stored is returned. 

pStatusBlockRet is the memory address of the ISAM status 
block in which the status codes from the operation are 
returned. 

Table 7-36 describes the StorelSAMRecord request block. 
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Table 7-36. StorelSAMRecord Request: Block 



Size 



Offset 


Parameter 


(bytes) 


Contents 


0 


sCntlnf o 


2 


6 


2 


nReqPbCb 


1 


2 


3 


nRespPbCb 


1 


1 


4 


userNum 


2 




6 


exchResp 


2 




8 


ercRet 


2 




10 


rqCode 


2 


94 


12 


ISAMHandle 


2 




14 


pRecord 


4 




18 


sRecord 


2 




20 


pUriRecordRet 


4 




24 


sUriRecord 


2 


4 


26 


pStatusBlockRet 


4 




30 


sStatusBlock 


2 


4 



VerifyMultiUserlSAM Procedure 

The VerifyMultiUserlSAM procedure sends a request to ISAM at 
either the B-NET node where the application is running or at 
another B-NET node. If ISAM is installed, a status code of 
0 (OK) is returned. Any other status code indicates that 
multiuser ISAM is not available. 

You can use the reserved symbols {Local} and {Master} 
whether or not B-Net is installed. 

VerifyMultiUserlSAM is an object module procedure. 

The procedural interface is: 

VerifyMultiUserlSAM (pbNode, cbNode, pStatusBlockRet): 

ercType 

pbNode and cbNode describe the memory area containing the 
name of the B-NET node. The default node is the master 
workstation for the cluster or the standalone workstation, 
where the application is running. 

pStatusBlockRet is the memory address of the status block 
into which the status codes from the operation are returned. 
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APPENDIX A 



STATUS CODES 



Decimal 
Value 

3100 



3101 



3102 



3103 



3104 



3105 
3106 



Hexa- 
decimal 
Value 

0C1C 



0C1D 



0C1E 



0C1F 



0C20 



0C21 
0C22 



Meaning 

No such index exists. 

An operation that includes a key 
was invoked, but the specified 
index does not exist. 

Prefix is not valid. 

SetUpISAMIterationPref ix was 
invoked for an index that is 
neither a byte nor character 
string. 

Dad key length. 

The key length is inconsistent with 
the index type. 

Bad ISAM or data base handle. 

The ISAM handle does not identify 
an open ISAM data set. 

Bad ISAM header size. 

The ISAM data set cannot be opened 
by the OpenlSAM operation due to an 
inconsistency in the header of one 
of the files of the data set. 

Bad ISAM header. See 3104 

Internal error. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3107 



3108 
3109 
3110 
3111 



3112 
3113 



3114 
3115 



3116 
3117 



Hexa- 
decimal 
Value 

0C23 



0C24 
0C25 
0C26 
0C27 



0C28 
0C29 



0C2A 
0C2B 



0C2C 
0C2D 



Meaning 

ISAM is already installed. 

This code is generated by the 
InstalllSAM operation or the ISAM 
INSTALL command if ISAM is already 
installed. 

Internal error. 

Internal error. 

Internal error. 

No free ISAM handles. 

The ISAM data set cannot be opened 
because the maximum ISAM data sets 
that can be simultaneously opened 
by all users combined (256) has 
been reached. 

Internal error. 

Buffers are too large 

The amount of RAM required by 
either the data store or index 
cache buffers exceeds a megabyte. 

Internal error. 

ISAM terminated abnormally. 

Following detection of an internal 
error, all subsequent ISAM 
operations and services generate 
this status code. 

Internal error. 

Bad unique record identifier. 

An incorrect unique record identi- 
fier parameter was passed to ISAM. 
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ISAM STATUS CODES (Conn) 



Decimal 
Value 

3118 



Hexa- 
decimal 
Value 



0C2E 



3119 



0C2F 



3120 



0C30 



3121 



0C31 



3122 



0C32 



3123 



0C33 



Meaning 

Duplicate key. 

An attempt to store or modify a 
record would duplicate the key 
stored in another record for the 
same index, but the index does not 
allow duplicates. 

Index file error. 

This status code is returned as the 
status code of an ISAM operation. 
The detail status code refers to a 
problem with the index file of the 
ISAM data set. 

Attempted privacy breach. 

An attempt was made to modify a 
data set that is open in batch read 
or transaction read mode. 

Bad request. 

Either the request block is 
invalid, or the parameters of an 
operation are inconsistent or have 
invalid values. 

Data store file error. 

This is returned as the status code 
of an ISAM operation. The detail 
status code refers to a problem 
with the data store file of the 
ISAM data set. 

Index to data error. 



An inconsistency has arisen between 
the index and data store files of 
the ISAM data set. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3124 



3125 



Hexa- 
decimal 
Value 

0C34 



0C35 



3126 



0C36 



3127 



0C37 



3128 



0C38 



3129 



0C39 



Meaning 

Record size incorrect. 

The specified record size is 
incorrect for the ISAM data set. 

Duplicates allowed. 

An operation specified a unique key 
parameter (that is, duplicates are 
not allowed), but the index allows 
duplicates . 

No such record exists. 

A unique key was used to identify a 
record, but no record is stored in 
the ISAM data set with that key. 

No more records. 

A ReadNextlSAMRecord (Hold) or 
GetlSAMRecords (Hold) operation has 
read all the records within the 
range specified for the current 
iteration. No record is read when 
this status code is generated. 

Bad key. 

Either (1) a key field is longer 
than 64 bytes or is defined to 
occupy bytes past the end of the 
record, or (2) a supplied key is 
invalid. For example, a DECIMAL 
key with a digit that is not 
between 0 and 9 is invalid. 

Bad index. 

The specified key field does not 
exist, that is, the Index parameter 
of an ISAM operation is greater 
than or equal to the number of 
indexes in the ISAM data set. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3130 



3131 



Hexa- 
decimal 
Value 

0C3A 



0C3B 



Meaning 

Bad ISAM mode. 

The mode parameter of the OpenlSAM 
operation is invalid. 

Cannot open ISAM. 

This is returned as the status code 
of an OpenlSAM operation. The 
detail status code gives the reason 
for this failure. 



3132 



0C3C 



3133 



3134 



0C3D 



0C3E 



3135 
3136 



0C3F 
0C40 



Bad ISAM password. 

Either the password does not give 
the access desired by the OpenlSAM 
operation, or the password is 
larger than the 12 bytes accepted 
by the SetlSAMProtection operation. 

Wrong record size. 

The OpenlSAM operation detects the 
wrong size record. 

Incompatible ISAM mode. 

An attempt was made to open a data 
set when the data set is already 
open in an incompatible mode. 

Internal error. 

Not administrator. 

An operation for which the data set 
must be open in administrator mode 
is attempted with the data set open 
in some other mode. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3137 



Hexa- 
decimal 
Value 

0C41 



3138 



0C42 



3139 
3140 



0C43 
0C44 



3141 



0C45 



3142 



0C46 



3143 



0C47 



Meaning 

Cannot create ISAM. 

This is returned as the status code 
of the CreatelSAM operation. The 
detail status code gives the reason 
for the failure. 

ISAM buffer is too small. 

The data set being opened or 
created requires buffers larger, 
than those installed. 

Internal error. 

Small ISAM record. 

An attempt was made to create an 
ISAM data set with records shorter 
than four bytes. 

Not in transaction. 

An operation that can be invoked 
only when the application is in a 
transaction was invoked while the 
application was not in a 
transaction. 

Data set or relation is not 
available. 

An attempt to read or hold a record 
or to hold a data set failed 
because the data set was held by 
another user. 

Record is not available. 

An attempt to read or hold a record 
failed because the record was held 
by another user. 



A- 6 



ISAM STATUS CODES (Cont) 



Decimal 
Value 

3144 



3145 



3146 

3147 
3148 



Hexa 

decimal 

Value 

0C48 



0C49 



0C4A 

0C4B 
0C4C 



3149 0C4D 

3150 0C4E 

3151 0C4F 



Meaning 

Record is not locked. 

An operation for which the record 
(or its data set) must be held was 
invoked when neither the record nor 
its data set was held. 

Too many records are locked. 

An attempt was made to hold a 
record when the maximum allowable 
number of records was already held. 

In transaction. 

BeginTransaction was invoked during 
a transaction. 

Internal error. 

Transaction purged. 

The application finished a 
transaction while the request was 
queued. (This status code is 
generated only if the application 
has a request pending when invoking 
RollBackTransaction or 
CommitTransaction . ) 

Internal error. 

Internal error. 

Data set is not locked. 

An operation for which the data set 
must be held was called when the 
data set was not held. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3152 



Hexa- 
decimal 
Value 

0C50 



3153 
3154 



0C51 
0C52 



3155 



0C53 



Meaning 

ISAM heap is full. 

The operation failed because there 
is not enough room in the ISAM 
server's heap to store data 
structures required by the 
operation. 

Internal error. 

Files are not on same workstation. 

An attempt was made to either 
create or rename a data set so that 
the data store and index files 
would be on different workstations 
or to open a data set (in other 
than administrator mode) that is 
on a different workstation from the 
one where the ISAM server is 
running. 

Bad match kind. 

A SetUpISAMIterationLimits 
operation contained an invalid 
matchKind argument. 



3156 



0C54 



Internal error. 



3157 0C55 Transaction barrier after 

modification. 

An ISAM transaction barrier 
operation was called after a 
modification to the data set or 
data base in the current 
transaction, but the 
SetTransactionParams operation was 
previously invoked with 
fBarrierAfterModify set to FALSE 
(0). 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3158 



Hexa- 
decimal 
Value 

0C56 



3159 



0C57 



3160 



0C58 



3161 



0C59 



3162 



0C5A 



Meaning 

Key is locked. 

This code is returned as the detail 
status code when the primary status 
code is 3143 (Record not avail- 
able). It indicates that the 
record was not available because of 
key locking constraints. 

Record is held. 

This code is returned as the detail 
status code when the primary status 
code is 3143 (Record not avail- 
able). It indicates that the 
record was not available because 
another user had locked it. 

Transaction has been rolled back. 

The applications current trans- 
action has been rolled back. This 
status code is returned for every 
operation by an application after 
a lock has been broken, until the 
application invokes the 
RollbackTransaction operation. 

Journal file error. 

An error has occurred during access 
to a journal file. See the detail 
error for more information. 

Journal open error. 

An error has occurred while opening 
the journal file. See the detail 
error for more information. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3163 



Hexa- 
decimal 
Value 

0C5B 



3164 



0C5C 



3165 



0C5D 



Meaning 

Journal close error. 

An error has occurred while closing 
the journal file. See the detail 
error for more information. 

Journal write error. 

An error has occurred while writing 
to the journal file. See the 
detail error for more information. 

Internal error. 

Journal record illegal. An error 
has occurred while reading the 
journal file during an attempt to 
roll back a transaction. A record 
in the journal file has an 
incorrect format. 



3166- 
3199 



0C5E- 
0C7F 



Internal errors. 



3200 0C80 Bad key type. 

The type field of a key 
specification for Sort/Merge or 
ISAM is invalid. 

3201 0C81 Incorrect key length. 

The cbKey field of a key 
specification for a Sort/Merge or 
ISAM operation does not correspond 
to the type field of the key 
specification. (For example, for 
binary keys, cbKey must be 2.) 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3202 



Hexa- 
decimal 
Value 

0C82 



3203- 
3299 

3300 



0C83- 
0CE3 

0CE4 



3301 



0CE5 



3302 



3303 



0CE6 



0CE7 



Meaning 

Bad key. 

A key contained in a record for 
Sort/Merge or ISAM, or a key 
described by a parameter of an 
ISAM operation is not of the 
correct type. (For example, each 
digit of a BCD key must be between 
0 and 9 . ) 



Internal errors. 
Not a STAM file. 

The operation failed because the 
file did not contain the proper 
signature . 

STAM header bad checksum. 

The operation failed because the 
checksum computed on the file 
header did not match the checksum 
computed when the file was 
created . 

Record does not exist. 

The operation failed because the 
specified record does not exist. 

Malformed record. 

The operation failed because data 
read from the disk contained an 
inconsistency in the record header 
and trailer. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 

3304 



Hexa- 

Decimal 

Value 

0CE8 



3305 



0CE9 



3306 



OCEA 



3307 



3308- 
3399 

3900 



OCEB 



0CEC- 
0D47 

0F3C 



3901 



0F3D 



Meaning 

Not fixed-length record. 

The operation failed because the 
access method cannot reference 
variable-length records. 

Bad file type. 

The operation failed because the 
file cannot be accessed with the 
specified access metnod. 

Bad buffer size. 

The operation failed because the 
buffer size was too small or not a 
multiple of 512. 

Buffer is not word-aligned. 

The operation failed because the 
buffer was not word-aligned. 

Internal errors. 

Cannot auto-restart. 

Because of a problem with the 
journal file, auto-restart recovery 
cannot be used to recover a data 
base (or one or more ISAM data 
sets). Use DB Recover to recover 
the data base. Recover ISAM data 
sets by another mechanism such as 
restoring archived copies. 

Bad ISAM configuration file 

An attempt was made to use a file 
as an ISAM configuration file, but 
the file has been damaged or it was 
not generated by ISAM Configure. 
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ISAM STATUS CODES (Cont) 



Decimal 
Value 



Hexa- 
decimal 
Value 



Meaning 



3902 



0F3E 



Bad ISAM configuration version 



An attempt was made to use an ISAM 
configuration file that was 
generated by an incompatible 
version of ISAM Configure. 
Regenerate the file by using a 
compatible version. 



3903- 
3999 



0F3F- 
0F9F 



Internal errors. 
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APPENDIX B 
UPWARD COMPATIBILITY SUPPORT 

ISAM 5.0 supports the use of applications written for 
previous releases of ISAM, even though ISAM's set of 
operations do not include these procedures. 

SUPERSEDED PROCEDURES 

The following eight operations are no longer part of the 
standard set of ISAM operations: 

• EndlSAMTransaction 

• LocKlSAM 

• PurgelSAMTransaction 

• SetupISAMIteration 

© SetupISAMIterationKey 

• SetupISAMIterationRange 

• StartlSAMTransaction 

• UnlocKlSAM 

ISAM supports all eight operations only as object modules 
(no longer request blocks). ISAM 5.0 handles each of these 
operations as described in this appendix. Refer to 
section 7, for descriptions of the current ISAM operations 
that are mentioned here. 

EndlSAMTransaction 

EndlSAMTransaction is equivalent to CommitTransaction. 
LocklSAM 

You implement LocklSAM by BeginTransaction followed by a 
series of HoldlSAMDataSet operations. 
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PurgelSAMTransaction 

PurgelSAMTransaction is equivalent to RollBackTransaction . 

SetupISAMIteration 

SetupISAMIterationKey 

SetupISAMIterationRange 

You implement these operations by equivalent calls to 
SetupISAMIterationLimits . 

StartlSAMTransaction 

You implement StartlSAMTransaction by BeginTransaction 
followed by a series of HoldlSAMDataSet operations. 

UnlocklSAM 

If the application uses UnlocklSAM in a transaction, this 
operation is equivalent to CommitTransaction; otherwise, 
UnlocklSAM has no effect. 

InstalllSAM SUPPORT 

Previous releases of ISAM used two libraries: ISAMSingle .Lib 
for single-user applications, and ISAMMulti.Lib for 
multiuser application. ISAMSingle. Lib included the ISAM 
procedural interfaces and all the implementing modules. The 
linked run file included all of ISAM. ISAMMulti.Lib 
included the ISAM procedural interfaces as request 
interfaces. The system sent requests to the multiuser ISAM 
service installed at the master workstation or a standalone 
workstation. 

The system provided InstalllSAM in previous ISAM releases to 
initialize single-user ISAM. The ISAMMulti.Lib version 
enabled compatibility; if allowed, you link an application 
as either a multiuser or single-user. The multiuser version 
determined whether or not the multiuser server was installed 
and returned an error status if it was not installed. 

In ISAM 5.0, there is only one library: ISAM. Lib. Single- 
user applications now call LoadSingleUserlSAM to load the 
ISAM service as a task. Multiuser applications can call 
VerifyMultiuserlSAM to determine whether or not the system 
installed the multiuser ISAM service. 
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To provide compatibility for applications that use 
InstalllSAM, there are two versions of InstalllSAM in 
ISAM. Lib. The module named IsaMin is the multiuser version; 
it calls VerifyMultiuserlSAM. The single-user version, the 
module IsaSin, calls LoadSingleUserlSAM . When you link an 
application that uses InstalllSAM, you must specify the 
appropriate version of InstalllSAM in the object modules 
line of the Link command form. For single-user 
applications, specify ISAM. Lib (IsaSin) when you link the run 
file. 

For multiuser applications, specify ISAM. Lib ( IsaMin) when 
you link the run file. 



B-TREE NODE SIZES 

In ISAM 5.0, the memory requirements for the ISAM server are 
significantly reduced without degrading performance. In 
releases prior to ISAM 4.0, the default B-tree node size 
was six sectors in ISAM CREATE, ISAM REORGANIZE, and the 
index buffers in ISAM INSTALL. The default B-tree node size 
in ISAM 5.0 is two sectors. 

For existing data sets where you did not set the B-tree node 
sizes to one or two sectors, you must do one of the 
following: 

• use ISAM REORGANIZE to rebuild the index file with 
2-sector B-tree nodes or 

• reconfigure ISAM with the ISAM CONFIGURE command 
to use larger index buffers (six sectors). 
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APPENDIX C 
ESTIMATED INDEX FILE SIZES 



B-tree nodes can fluctuate between 50 percent and 100 
percent full. Adding a key to a full node causes the node 
to split into two 50 percent full nodes. A key is also 
added to the B-tree node above the full node that split. 
When the full node is the root node, the current root node 
splits into two 50 percent full nodes, and ISAM creates a 
new root node with two nodes below it. This introduces a 
new level in the B-tree. 

Removing a key from a 50 percent full node causes absorption 
of the node by its neighbors. ISAM uses either one or two 
nodes to eliminate the node that is now less than 50 percent 
full. The current size of the neighbor nodes determines the 
distribution of the keys. The result is that one or two 
nodes become at least two-thirds full. 

When ISAM eliminates a node, it deletes a key from the node 
one level up in the B-tree. If eliminating a node causes 
the root node to have only one node below it at the next 
level, ISAM deletes the root node. The next lowest level 
becomes the root node, and the B-tree has one less level. 



INDEX FILE SIZES 



You can only compute the exact size of an index file 
immediately after ISAM rebuilds the indexes. After a series 
of updates (additions, modifications, deletions), you can 
only estimate the size. 

You base the estimate on: 

• the number of records in the data set, n 

• the definition of the indexes 

• the average load factor, f_, which is the fraction 
of each B-tree node that is in use 

Whenever ISAM rebuilds the indexes for a relation, the 
loading factor for the B-tree nodes is 80 percent full. 
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As ISAM stores, modifies, or deletes records, the portion of 
the node that fills varies between 50 percent and 100 
percent. The node never falls below 50 percent full, and it 
is likely to remain near 80 percent full most of the time. 

Example and Calculations 

This example uses a relation with: 

• 50,000 records 

• a 10-byte key 

• a 4-byte key 

• 6-sector nodes 

If the load factor, f_, is 80 percent, then you calculate the 
index file size as follows: 

1. the average number of keys per node: 

10-byte key: b = 0.8 * 6*512 - 16 = 174.6 

10 + 4 



4-byte key: b = 0.8 * 6*512 - 16 = 305.6 

4 + 4 

2. the index sizes: 

10-byte key: 6*50000* ( 1/174 . 6 + 2/174. 6 2 ) 
= 1738 sectors 

4-byte key: 6*50000* ( 1/305 . 6 + 2/305. 6 2 ) 
= 989 sectors 

total size = 2727 sectors 
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Similar computations for f_ = 50 percent and f = 100 percent 
yield the following: 

1. for 50 percent: 

10-byte key: b = 109 

index size = 2803 sectors 

4-byte key: b = 191 

index size = 1587 sectors 



total size 
2. for 100 percent: 



= 4390 sectors 



10-byte key: b = 218 

index size = 1389 sectors 



4-byte key: b = 382 

index size 

total size 



789 sectors 
2178 sectors 
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APPENDIX D 
GLOSSARY 



Access Mode 

An access mode is the method of opening a data set to read 
or modify records. The access mode affects the extent to 
which other application systems can share the data set. 

Administrator Mode 

Administrator mode is an access mode you use to perform data 
set-level activities such as deleting, renaming, and 'setting 
protection . 

Application 

An application is a task you invoke to access a data set for 
a particular program. 

Asynchronous Request 

An asynchronous request is a method of accessing ISAM system 
services directly so that data set access and internal 
computations overlap. Asynchronous requests allow 
applications to execute more efficiently and rapidly than a 
procedural interface method. 

B-Tree 

A B-tree is the type of structure used to contain ISAM 
indexes. A B-tree is usually pictured as an upside down 
tree, much like a family tree, with a "root" node at the top 
and "leaf" nodes below the root. 

Configuration File 

A configuration file specifies the sizes of the ISAM 
server ' s memory areas according to the number of users 
utilizing the server. 

DAM 

See Direct Access Method. 
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Data Buffer 



A data buffer is an I/O buffer into which ISAM reads 
portions of data files. 

Data Set 

A data set contains one type of fixed-length records. ISAM 
accesses them through fixed-length keys. 

Data Store File 

A data store file is the physical file that holds the 
records of a data set. 

Deadlock 

Deadlock occurs when two or more transactions request 
records or data sets already locked by the other 
transaction. 

Direct Access Method 

The Direct Access Method (DAM) provides random access to 
disk file records identified by record number. 

Exclusive Access 

Exclusive access limits the accessibility of a data set or 
record to a single user. Compare with Shared Access. 

File 

A file is a set of related records (on a disk) treated as a 
unit. 

Heap 

A heap is an area of memory containing internal ISAM data 
structures. 

Index 

ISAM uses an index (structure) to locate particular records 
within a data set. Each key field of a data set defines one 
index. Also see Key and Record. 

Index Buffer 

An index buffer is an I/O buffer into which ISAM reads 
B-tree nodes. Also see B-Tree and Node. 
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Indexed Sequential Access Method (ISAM) 

The Indexed Sequential Access Method provides random access 
to fixed-length records identified by multiple keys stored 
in disk files. Compare with Direct Access Method and Record 
Sequential Access Method. 

Index File 

An index file holds the indexes for all of the data set's 
keys . 

ISAM Handle 

An ISAM handle is a word value used in ISAM operations to 
identify an open data set. 

Key 

ISAM uses keys to access data set records. ISAM defines a 
key by its position in the record, its length, and type. 

Key Type 

Key types support the various character and numeric 
representations used by the B 20 programming languages and 
processors . 

Locking 

Locking is the process of obtaining Exclusive Access to a 
record or data set in multiuser ISAM. 

Node 

A node is a portion of a B-tree that stores index keys. 
Password 

A password is a text string used to validate an application 
or user's access to the data set. 

Record 

A record is a group of related data fields treated as a 
unit. 

Record Sequential Access Method 

The Record Sequential Access Method (RSAM) provides 
sequential read-only access to the records of a data set. 
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Reorganization 

Reorganization is the process of freeing up space in a data 
set by removing deleted records and rebuilding the indexes 
for the data set. 

RSAM 

See Record Sequential Access Method. 
Shared Access 

Shared access enables multiple users to simultaneously 
access the same data set. Compare with Exclusive Access. 

Status Block 

A status block is a 4-byte memory area that ISAM uses to 
report status codes to an application. 

Swap Zone 

A swap zone is a virtual code segment management buffer. 
Timeout 

ISAM uses timeouts to prevent a deadlock. A timeout value 
specifies the maximum time a request to lock a data set or 
record can queue. Also see Deadlock. 

Transaction 

A transaction is a unit of work. Transactions permit shared 
access to a data set. 

Unique Record Identifier (URI) 

A Unique Record Identifier is a 4-byte unsigned integer used 
to identify a record in a data set. 

Write-Through Cache 

The write-through cache is a set of I/O buffers that ISAM 
uses to bring segments of disk records into memory as 
needed. 
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Data (continued) 

integrity, 2-13 
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Data set, D-2 

access 7-8 
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loading a, 5-7 
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management operations, 7-3 
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Function 
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GetlSAMRecords 
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operation, 7-8 
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